@revenexx/app-sdk 0.8.0 → 1.0.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.
@@ -1,5 +1,102 @@
1
- import { m as SettingsDefaults, k as ReadOptions, l as ResolvedSettings, p as SettingsSnapshot, o as SettingsReader, n as SettingsOptions, Q as Query, R as Row, P as Page } from '../errors-D7FGkghT.cjs';
2
- export { D as DEFAULT_GATEWAY_ENDPOINT, e as DEFAULT_SETTINGS_ERROR_TTL_MS, f as DEFAULT_SETTINGS_TIMEOUT_MS, g as DEFAULT_SETTINGS_TTL_MS, H as HttpError, j as HttpErrorOptions, q as SettingsSource, t as badRequest, u as conflict, r as createSettings, v as forbidden, s as isHttpError, w as notFound } from '../errors-D7FGkghT.cjs';
1
+ import { m as SettingsDefaults, k as ReadOptions, l as ResolvedSettings, p as SettingsSnapshot, o as SettingsReader, n as SettingsOptions, Q as Query, R as Row, P as Page } from '../errors-BPYDadk4.cjs';
2
+ export { D as DEFAULT_GATEWAY_ENDPOINT, e as DEFAULT_SETTINGS_ERROR_TTL_MS, f as DEFAULT_SETTINGS_TIMEOUT_MS, g as DEFAULT_SETTINGS_TTL_MS, H as HttpError, j as HttpErrorOptions, q as SettingsSource, t as badRequest, u as conflict, r as createSettings, v as forbidden, s as isHttpError, w as notFound } from '../errors-BPYDadk4.cjs';
3
+
4
+ /**
5
+ * Who is acting — the person behind a request, as the platform established
6
+ * them.
7
+ *
8
+ * An app has always been told which TENANT a call is for. Which PERSON was a
9
+ * different question, and for a long time it had no answer: the brokered
10
+ * context identifies the calling system (in a theme site, the theme's service
11
+ * user — a robot with no name), the gateway strips inbound identity headers
12
+ * because they are forgeable, and anything in the request body is the caller's
13
+ * own word about itself. Apps that needed a person resolved one out of the
14
+ * context's email claim and hoped, or read an `_actor` out of the body and
15
+ * called it attribution rather than authentication, because that is all it was.
16
+ *
17
+ * The gateway now states it (RAD-12), on two planes:
18
+ *
19
+ * - ASSERTED. A storefront call is made by a server — the theme BFF, holding
20
+ * the tenant API key — on behalf of a customer. The credential proves the
21
+ * tenant, so the caller names the person and the gateway resolves that name
22
+ * through the tenant's role provider. It defends against a malicious end
23
+ * user, not against a compromised BFF.
24
+ * - AUTHENTICATED. A Cockpit call, or any call carrying a person's own
25
+ * Zitadel token, needs nobody's word: the signature and issuer were
26
+ * verified before a route was matched, and the contact — if there is one —
27
+ * was resolved from that proven subject.
28
+ *
29
+ * Both arrive in the same headers, which is exactly why `trust` exists. The
30
+ * same `contact` is a signature on one plane and a label on the other, and an
31
+ * app deciding an approval has to be able to tell the two apart. An app that
32
+ * only attributes — a "last edited by" — can ignore it.
33
+ *
34
+ * Every header read here is set ONLY by the gateway: it builds a fresh header
35
+ * set per dispatch and strips any copy a caller sent. So `actor.trust` cannot
36
+ * be talked up from outside, and an app never has to decide whether to believe
37
+ * a header — only what to do with what it says.
38
+ */
39
+ /** How the platform came to know who is acting. */
40
+ type ActorTrust = 'authenticated' | 'asserted' | 'none';
41
+ /**
42
+ * Which side of the platform the caller is on.
43
+ *
44
+ * - `contact` — one of the tenant's own people: a buyer, an approver.
45
+ * - `operator` — a human the PLATFORM knows and the tenant's records do not.
46
+ * Back office: Cockpit staff, support, a partner operating the tenant. There
47
+ * is no contact to check a per-row rule against, and that absence is the
48
+ * signal, not a failure to resolve one.
49
+ * - `system` — nobody: a schedule, a webhook, a service token, an in-mesh call.
50
+ *
51
+ * This is the distinction apps otherwise make by hand, badly — usually by
52
+ * treating "no contact resolved" as "must be the platform", which is also what
53
+ * an unknown customer looks like.
54
+ */
55
+ type ActorPlane = 'contact' | 'operator' | 'system';
56
+ /** The acting person, as far as the platform can state it. */
57
+ interface Actor {
58
+ /** The authenticated human's platform subject, or null when none was proven. */
59
+ user: string | null;
60
+ /** Their email claim, or null. Attribution — never a lookup key to trust on its own. */
61
+ email: string | null;
62
+ /** The `customers` contact the platform resolved them to, or null. */
63
+ contact: string | null;
64
+ /** That contact's organization, or null. */
65
+ organization: string | null;
66
+ /** The permissions the tenant's role provider granted them. Empty when there is no contact. */
67
+ permissions: string[];
68
+ /** How well `contact` is known. `none` when nobody was established at all. */
69
+ trust: ActorTrust;
70
+ /** Which side of the platform the caller is on. */
71
+ plane: ActorPlane;
72
+ /** Does this actor hold the permission? False for every permission when nobody is acting. */
73
+ holds(permission: string): boolean;
74
+ /**
75
+ * Is this a person the platform itself authenticated?
76
+ *
77
+ * The one check a per-person rule should make. An app enforcing "only the
78
+ * approver this approval names may decide it" needs a signature, and only
79
+ * this plane produces one.
80
+ */
81
+ authenticated(): boolean;
82
+ }
83
+ /** Gateway-set headers. Named here so a reader can grep the wire format. */
84
+ declare const ACTOR_HEADERS: {
85
+ readonly user: "x-revenexx-actor";
86
+ readonly email: "x-revenexx-actor-email";
87
+ readonly trust: "x-revenexx-actor-trust";
88
+ readonly contact: "x-revenexx-contact";
89
+ readonly organization: "x-revenexx-organization";
90
+ readonly permissions: "x-revenexx-permissions";
91
+ };
92
+ /**
93
+ * Read the acting person out of a request's headers.
94
+ *
95
+ * Unknown values of the trust header degrade to `asserted` rather than to
96
+ * `authenticated`: a gateway that learns a third plane must not silently
97
+ * promote it past a signature check written today.
98
+ */
99
+ declare function actorFrom(header: (name: string) => string | undefined): Actor;
3
100
 
4
101
  /**
5
102
  * Minimal HTTP router for revenexx App functions.
@@ -57,6 +154,17 @@ interface RouteContext<D extends SettingsDefaults = SettingsDefaults> {
57
154
  tenant: string | null;
58
155
  /** The forwarded identity token (`x-revenexx-context`), if present. */
59
156
  contextToken: string;
157
+ /**
158
+ * Who is acting — the person behind this request, as the platform
159
+ * established them (see ./actor.ts).
160
+ *
161
+ * `c.tenant` says whose data this is; this says whose hand is on it. Read
162
+ * `c.actor.authenticated()` before enforcing a per-person rule, and
163
+ * `c.actor.plane` to tell one of the tenant's contacts from a back-office
164
+ * operator from a system caller. Never derive either from the context
165
+ * token's claims: those describe the calling SYSTEM.
166
+ */
167
+ actor: Actor;
60
168
  /** Case-insensitive header lookup. */
61
169
  header(name: string): string;
62
170
  log(message: string): void;
@@ -149,8 +257,26 @@ interface RepoLike {
149
257
  interface CrudOptions {
150
258
  /** Route base path, e.g. `/markets` or `/markets/{marketId}/locales`. */
151
259
  path: string;
152
- /** Column metadata (from the generated ENTITIES) — enables `?col=value` list filters. */
260
+ /**
261
+ * Column metadata (from the generated ENTITIES) — enables `?col=value` list
262
+ * filters. A list query key that is neither a column, a reserved key
263
+ * (`limit`, `offset`, `order`) nor declared in `queryParams` is refused with
264
+ * `400 unknown_filter`. Without `columns`, only those keys are accepted.
265
+ */
153
266
  columns?: Record<string, unknown>;
267
+ /**
268
+ * Extra list query parameters the App handles itself (e.g. read by
269
+ * middleware, a wrapping handler, or simply tolerated). The list route
270
+ * accepts them and does NOT turn them into filters — they never reach the
271
+ * data plane and are not echoed in `filter`.
272
+ *
273
+ * mountCrud(app, db.accounts, {
274
+ * path: '/punchout/accounts',
275
+ * columns: ENTITIES.accounts.columns,
276
+ * queryParams: ['include_secrets'],
277
+ * });
278
+ */
279
+ queryParams?: string[];
154
280
  /**
155
281
  * Nested-resource scoping: path param name + the FK column it maps to.
156
282
  *
@@ -177,6 +303,11 @@ interface CrudOptions {
177
303
  /** Restrict which routes are mounted (default: all five). */
178
304
  only?: ('list' | 'get' | 'create' | 'update' | 'delete')[];
179
305
  }
306
+ /**
307
+ * Query keys the list route reads itself. Always accepted, never filters (a
308
+ * column of the same name is still filtered on as well, as before).
309
+ */
310
+ declare const RESERVED_LIST_QUERY_KEYS: readonly string[];
180
311
  declare function mountCrud<D extends SettingsDefaults = SettingsDefaults>(app: App<D>, repo: RepoLike, opts: CrudOptions): App<D>;
181
312
 
182
- export { type App, type AppOptions, type CrudOptions, type FnContext, type FnRequest, type FnResponse, type Handler, ReadOptions, type RepoLike, ResolvedSettings, type RouteContext, SettingsDefaults, SettingsOptions, SettingsReader, SettingsSnapshot, createApp, mountCrud };
313
+ export { ACTOR_HEADERS, type Actor, type ActorPlane, type ActorTrust, type App, type AppOptions, type CrudOptions, type FnContext, type FnRequest, type FnResponse, type Handler, RESERVED_LIST_QUERY_KEYS, ReadOptions, type RepoLike, ResolvedSettings, type RouteContext, SettingsDefaults, SettingsOptions, SettingsReader, SettingsSnapshot, actorFrom, createApp, mountCrud };
@@ -1,5 +1,102 @@
1
- import { m as SettingsDefaults, k as ReadOptions, l as ResolvedSettings, p as SettingsSnapshot, o as SettingsReader, n as SettingsOptions, Q as Query, R as Row, P as Page } from '../errors-D7FGkghT.js';
2
- export { D as DEFAULT_GATEWAY_ENDPOINT, e as DEFAULT_SETTINGS_ERROR_TTL_MS, f as DEFAULT_SETTINGS_TIMEOUT_MS, g as DEFAULT_SETTINGS_TTL_MS, H as HttpError, j as HttpErrorOptions, q as SettingsSource, t as badRequest, u as conflict, r as createSettings, v as forbidden, s as isHttpError, w as notFound } from '../errors-D7FGkghT.js';
1
+ import { m as SettingsDefaults, k as ReadOptions, l as ResolvedSettings, p as SettingsSnapshot, o as SettingsReader, n as SettingsOptions, Q as Query, R as Row, P as Page } from '../errors-BPYDadk4.js';
2
+ export { D as DEFAULT_GATEWAY_ENDPOINT, e as DEFAULT_SETTINGS_ERROR_TTL_MS, f as DEFAULT_SETTINGS_TIMEOUT_MS, g as DEFAULT_SETTINGS_TTL_MS, H as HttpError, j as HttpErrorOptions, q as SettingsSource, t as badRequest, u as conflict, r as createSettings, v as forbidden, s as isHttpError, w as notFound } from '../errors-BPYDadk4.js';
3
+
4
+ /**
5
+ * Who is acting — the person behind a request, as the platform established
6
+ * them.
7
+ *
8
+ * An app has always been told which TENANT a call is for. Which PERSON was a
9
+ * different question, and for a long time it had no answer: the brokered
10
+ * context identifies the calling system (in a theme site, the theme's service
11
+ * user — a robot with no name), the gateway strips inbound identity headers
12
+ * because they are forgeable, and anything in the request body is the caller's
13
+ * own word about itself. Apps that needed a person resolved one out of the
14
+ * context's email claim and hoped, or read an `_actor` out of the body and
15
+ * called it attribution rather than authentication, because that is all it was.
16
+ *
17
+ * The gateway now states it (RAD-12), on two planes:
18
+ *
19
+ * - ASSERTED. A storefront call is made by a server — the theme BFF, holding
20
+ * the tenant API key — on behalf of a customer. The credential proves the
21
+ * tenant, so the caller names the person and the gateway resolves that name
22
+ * through the tenant's role provider. It defends against a malicious end
23
+ * user, not against a compromised BFF.
24
+ * - AUTHENTICATED. A Cockpit call, or any call carrying a person's own
25
+ * Zitadel token, needs nobody's word: the signature and issuer were
26
+ * verified before a route was matched, and the contact — if there is one —
27
+ * was resolved from that proven subject.
28
+ *
29
+ * Both arrive in the same headers, which is exactly why `trust` exists. The
30
+ * same `contact` is a signature on one plane and a label on the other, and an
31
+ * app deciding an approval has to be able to tell the two apart. An app that
32
+ * only attributes — a "last edited by" — can ignore it.
33
+ *
34
+ * Every header read here is set ONLY by the gateway: it builds a fresh header
35
+ * set per dispatch and strips any copy a caller sent. So `actor.trust` cannot
36
+ * be talked up from outside, and an app never has to decide whether to believe
37
+ * a header — only what to do with what it says.
38
+ */
39
+ /** How the platform came to know who is acting. */
40
+ type ActorTrust = 'authenticated' | 'asserted' | 'none';
41
+ /**
42
+ * Which side of the platform the caller is on.
43
+ *
44
+ * - `contact` — one of the tenant's own people: a buyer, an approver.
45
+ * - `operator` — a human the PLATFORM knows and the tenant's records do not.
46
+ * Back office: Cockpit staff, support, a partner operating the tenant. There
47
+ * is no contact to check a per-row rule against, and that absence is the
48
+ * signal, not a failure to resolve one.
49
+ * - `system` — nobody: a schedule, a webhook, a service token, an in-mesh call.
50
+ *
51
+ * This is the distinction apps otherwise make by hand, badly — usually by
52
+ * treating "no contact resolved" as "must be the platform", which is also what
53
+ * an unknown customer looks like.
54
+ */
55
+ type ActorPlane = 'contact' | 'operator' | 'system';
56
+ /** The acting person, as far as the platform can state it. */
57
+ interface Actor {
58
+ /** The authenticated human's platform subject, or null when none was proven. */
59
+ user: string | null;
60
+ /** Their email claim, or null. Attribution — never a lookup key to trust on its own. */
61
+ email: string | null;
62
+ /** The `customers` contact the platform resolved them to, or null. */
63
+ contact: string | null;
64
+ /** That contact's organization, or null. */
65
+ organization: string | null;
66
+ /** The permissions the tenant's role provider granted them. Empty when there is no contact. */
67
+ permissions: string[];
68
+ /** How well `contact` is known. `none` when nobody was established at all. */
69
+ trust: ActorTrust;
70
+ /** Which side of the platform the caller is on. */
71
+ plane: ActorPlane;
72
+ /** Does this actor hold the permission? False for every permission when nobody is acting. */
73
+ holds(permission: string): boolean;
74
+ /**
75
+ * Is this a person the platform itself authenticated?
76
+ *
77
+ * The one check a per-person rule should make. An app enforcing "only the
78
+ * approver this approval names may decide it" needs a signature, and only
79
+ * this plane produces one.
80
+ */
81
+ authenticated(): boolean;
82
+ }
83
+ /** Gateway-set headers. Named here so a reader can grep the wire format. */
84
+ declare const ACTOR_HEADERS: {
85
+ readonly user: "x-revenexx-actor";
86
+ readonly email: "x-revenexx-actor-email";
87
+ readonly trust: "x-revenexx-actor-trust";
88
+ readonly contact: "x-revenexx-contact";
89
+ readonly organization: "x-revenexx-organization";
90
+ readonly permissions: "x-revenexx-permissions";
91
+ };
92
+ /**
93
+ * Read the acting person out of a request's headers.
94
+ *
95
+ * Unknown values of the trust header degrade to `asserted` rather than to
96
+ * `authenticated`: a gateway that learns a third plane must not silently
97
+ * promote it past a signature check written today.
98
+ */
99
+ declare function actorFrom(header: (name: string) => string | undefined): Actor;
3
100
 
4
101
  /**
5
102
  * Minimal HTTP router for revenexx App functions.
@@ -57,6 +154,17 @@ interface RouteContext<D extends SettingsDefaults = SettingsDefaults> {
57
154
  tenant: string | null;
58
155
  /** The forwarded identity token (`x-revenexx-context`), if present. */
59
156
  contextToken: string;
157
+ /**
158
+ * Who is acting — the person behind this request, as the platform
159
+ * established them (see ./actor.ts).
160
+ *
161
+ * `c.tenant` says whose data this is; this says whose hand is on it. Read
162
+ * `c.actor.authenticated()` before enforcing a per-person rule, and
163
+ * `c.actor.plane` to tell one of the tenant's contacts from a back-office
164
+ * operator from a system caller. Never derive either from the context
165
+ * token's claims: those describe the calling SYSTEM.
166
+ */
167
+ actor: Actor;
60
168
  /** Case-insensitive header lookup. */
61
169
  header(name: string): string;
62
170
  log(message: string): void;
@@ -149,8 +257,26 @@ interface RepoLike {
149
257
  interface CrudOptions {
150
258
  /** Route base path, e.g. `/markets` or `/markets/{marketId}/locales`. */
151
259
  path: string;
152
- /** Column metadata (from the generated ENTITIES) — enables `?col=value` list filters. */
260
+ /**
261
+ * Column metadata (from the generated ENTITIES) — enables `?col=value` list
262
+ * filters. A list query key that is neither a column, a reserved key
263
+ * (`limit`, `offset`, `order`) nor declared in `queryParams` is refused with
264
+ * `400 unknown_filter`. Without `columns`, only those keys are accepted.
265
+ */
153
266
  columns?: Record<string, unknown>;
267
+ /**
268
+ * Extra list query parameters the App handles itself (e.g. read by
269
+ * middleware, a wrapping handler, or simply tolerated). The list route
270
+ * accepts them and does NOT turn them into filters — they never reach the
271
+ * data plane and are not echoed in `filter`.
272
+ *
273
+ * mountCrud(app, db.accounts, {
274
+ * path: '/punchout/accounts',
275
+ * columns: ENTITIES.accounts.columns,
276
+ * queryParams: ['include_secrets'],
277
+ * });
278
+ */
279
+ queryParams?: string[];
154
280
  /**
155
281
  * Nested-resource scoping: path param name + the FK column it maps to.
156
282
  *
@@ -177,6 +303,11 @@ interface CrudOptions {
177
303
  /** Restrict which routes are mounted (default: all five). */
178
304
  only?: ('list' | 'get' | 'create' | 'update' | 'delete')[];
179
305
  }
306
+ /**
307
+ * Query keys the list route reads itself. Always accepted, never filters (a
308
+ * column of the same name is still filtered on as well, as before).
309
+ */
310
+ declare const RESERVED_LIST_QUERY_KEYS: readonly string[];
180
311
  declare function mountCrud<D extends SettingsDefaults = SettingsDefaults>(app: App<D>, repo: RepoLike, opts: CrudOptions): App<D>;
181
312
 
182
- export { type App, type AppOptions, type CrudOptions, type FnContext, type FnRequest, type FnResponse, type Handler, ReadOptions, type RepoLike, ResolvedSettings, type RouteContext, SettingsDefaults, SettingsOptions, SettingsReader, SettingsSnapshot, createApp, mountCrud };
313
+ export { ACTOR_HEADERS, type Actor, type ActorPlane, type ActorTrust, type App, type AppOptions, type CrudOptions, type FnContext, type FnRequest, type FnResponse, type Handler, RESERVED_LIST_QUERY_KEYS, ReadOptions, type RepoLike, ResolvedSettings, type RouteContext, SettingsDefaults, SettingsOptions, SettingsReader, SettingsSnapshot, actorFrom, createApp, mountCrud };
@@ -5,6 +5,7 @@ import {
5
5
  DEFAULT_SETTINGS_TTL_MS,
6
6
  EMPTY_UPDATE_MESSAGE,
7
7
  HttpError,
8
+ OPS,
8
9
  badRequest,
9
10
  conflict,
10
11
  createSettings,
@@ -12,8 +13,44 @@ import {
12
13
  isHttpError,
13
14
  notFound,
14
15
  updateFields
15
- } from "../chunk-2BOFXTTC.js";
16
- import "../chunk-TUTGCI5D.js";
16
+ } from "../chunk-73D37ZGB.js";
17
+
18
+ // src/instrument.ts
19
+ var started = false;
20
+ async function startTelemetry() {
21
+ if (started) {
22
+ return;
23
+ }
24
+ started = true;
25
+ const endpoint = process.env["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] ?? process.env["OTEL_EXPORTER_OTLP_ENDPOINT"] ?? "";
26
+ if (!endpoint) {
27
+ return;
28
+ }
29
+ try {
30
+ const [{ NodeSDK }, { OTLPTraceExporter }, { UndiciInstrumentation }] = await Promise.all([
31
+ import("@opentelemetry/sdk-node"),
32
+ import("@opentelemetry/exporter-trace-otlp-proto"),
33
+ import("@opentelemetry/instrumentation-undici")
34
+ ]);
35
+ const sdk = new NodeSDK({
36
+ traceExporter: new OTLPTraceExporter(),
37
+ instrumentations: [new UndiciInstrumentation()]
38
+ });
39
+ sdk.start();
40
+ const flush = () => {
41
+ void sdk.shutdown().catch(() => {
42
+ });
43
+ };
44
+ process.once("SIGTERM", flush);
45
+ process.once("SIGINT", flush);
46
+ } catch (err) {
47
+ console.error(
48
+ "[app-sdk] OpenTelemetry init failed, continuing without tracing:",
49
+ err instanceof Error ? err.message : err
50
+ );
51
+ }
52
+ }
53
+ void startTelemetry();
17
54
 
18
55
  // src/router/router.ts
19
56
  import {
@@ -23,6 +60,43 @@ import {
23
60
  SpanKind,
24
61
  SpanStatusCode
25
62
  } from "@opentelemetry/api";
63
+
64
+ // src/router/actor.ts
65
+ var ACTOR_HEADERS = {
66
+ user: "x-revenexx-actor",
67
+ email: "x-revenexx-actor-email",
68
+ trust: "x-revenexx-actor-trust",
69
+ contact: "x-revenexx-contact",
70
+ organization: "x-revenexx-organization",
71
+ permissions: "x-revenexx-permissions"
72
+ };
73
+ var nullIfEmpty = (v) => v.trim() === "" ? null : v.trim();
74
+ function actorFrom(header) {
75
+ const read = (name) => {
76
+ const v = header(name);
77
+ return typeof v === "string" ? v : "";
78
+ };
79
+ const user = nullIfEmpty(read(ACTOR_HEADERS.user));
80
+ const contact = nullIfEmpty(read(ACTOR_HEADERS.contact));
81
+ const permissions = read(ACTOR_HEADERS.permissions).split(",").map((p) => p.trim()).filter(Boolean);
82
+ const raw = read(ACTOR_HEADERS.trust).trim().toLowerCase();
83
+ const trust = user === null && contact === null ? "none" : user !== null && raw === "authenticated" ? "authenticated" : "asserted";
84
+ const plane = contact !== null ? "contact" : user !== null ? "operator" : "system";
85
+ const held = new Set(permissions);
86
+ return {
87
+ user,
88
+ email: nullIfEmpty(read(ACTOR_HEADERS.email)),
89
+ contact,
90
+ organization: nullIfEmpty(read(ACTOR_HEADERS.organization)),
91
+ permissions,
92
+ trust,
93
+ plane,
94
+ holds: (permission) => permission !== "" && held.has(permission),
95
+ authenticated: () => trust === "authenticated"
96
+ };
97
+ }
98
+
99
+ // src/router/router.ts
26
100
  var splitPath = (path) => path.split("/").filter(Boolean);
27
101
  function compileTemplate(template) {
28
102
  return splitPath(template).map((seg) => {
@@ -179,9 +253,9 @@ function createApp(options = {}) {
179
253
  span.setAttribute("http.response.status_code", status);
180
254
  span.setStatus({ code: SpanStatusCode.ERROR, message: pathExists ? "method not allowed" : "no route" });
181
255
  if (pathExists) {
182
- return res.json({ error: `method ${method} not allowed for ${path}` }, 405);
256
+ return res.json({ error: `method ${method} not allowed for ${path}`, code: "method_not_allowed" }, 405);
183
257
  }
184
- return res.json({ error: `no route for ${method} ${path}`, routes: app.routes() }, 404);
258
+ return res.json({ error: `no route for ${method} ${path}`, code: "no_route", routes: app.routes() }, 404);
185
259
  }
186
260
  span.updateName(`${method} ${matched.route.template}`);
187
261
  span.setAttribute("http.route", matched.route.template);
@@ -202,6 +276,7 @@ function createApp(options = {}) {
202
276
  tenant,
203
277
  contextToken,
204
278
  header: (name) => headerOf(headers, name),
279
+ actor: actorFrom((name) => headerOf(headers, name)),
205
280
  log,
206
281
  json: (data, statusCode = 200) => res.json(data, statusCode),
207
282
  // The market rides on the request, so a market-scoped setting
@@ -230,14 +305,11 @@ function createApp(options = {}) {
230
305
  );
231
306
  }
232
307
  const msg = err instanceof Error ? err.message : String(err);
233
- if (/not permitted/.test(msg)) {
234
- span.setAttribute("http.response.status_code", 403);
235
- return res.json({ error: msg }, 403);
236
- }
308
+ span.setAttribute("http.response.status_code", 500);
237
309
  span.recordException(err instanceof Error ? err : new Error(msg));
238
310
  span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
239
311
  context.error?.(`unhandled error on ${method} ${path}: ${msg}`);
240
- return res.json({ error: msg }, 500);
312
+ return res.json({ error: "internal error", code: "internal_error" }, 500);
241
313
  } finally {
242
314
  span.end();
243
315
  }
@@ -250,6 +322,7 @@ function createApp(options = {}) {
250
322
  }
251
323
 
252
324
  // src/router/crud.ts
325
+ var RESERVED_LIST_QUERY_KEYS = Object.freeze(["limit", "offset", "order"]);
253
326
  var INT = (v, d) => {
254
327
  const n = parseInt(String(v), 10);
255
328
  return Number.isFinite(n) ? n : d;
@@ -267,21 +340,46 @@ function assertJsonFilter(column, value) {
267
340
  );
268
341
  }
269
342
  }
343
+ function assertKnownKeys(query, opts) {
344
+ const columns = opts.columns ?? {};
345
+ const extra = opts.queryParams ?? [];
346
+ const known = (k) => Object.prototype.hasOwnProperty.call(columns, k) || RESERVED_LIST_QUERY_KEYS.includes(k) || extra.includes(k);
347
+ const unknown = Object.keys(query).filter((k) => !known(k));
348
+ if (unknown.length === 0) return;
349
+ const allowed = [.../* @__PURE__ */ new Set([...Object.keys(columns), ...RESERVED_LIST_QUERY_KEYS, ...extra])].sort();
350
+ const quoted = unknown.map((k) => `'${k}'`).join(", ");
351
+ throw new HttpError(
352
+ 400,
353
+ `unknown list filter ${quoted} \u2014 not a column of this resource. A filter that cannot be applied is refused rather than ignored; see details.allowed.`,
354
+ { unknown, allowed },
355
+ { code: "unknown_filter" }
356
+ );
357
+ }
358
+ var OPERATOR_PREFIX = new RegExp(`^(?:not|${[...OPS].join("|")})\\.`);
359
+ function assertNoOperator(column, value) {
360
+ if (!OPERATOR_PREFIX.test(value)) return;
361
+ throw new HttpError(
362
+ 400,
363
+ `filter '${column}' carries an operator ('${value.slice(0, value.indexOf(".") + 1)}') \u2014 a list filters by exact value only; operators and value lists are not supported.`,
364
+ { parameter: column },
365
+ { code: "unsupported_filter_operator" }
366
+ );
367
+ }
270
368
  function parentWhere(c, parent) {
271
369
  if (!parent) return {};
272
370
  const value = c.params[parent.param];
273
- if (!value) throw new HttpError(400, `missing path parameter '${parent.param}'`);
371
+ if (!value) throw new HttpError(400, `missing path parameter '${parent.param}'`, void 0, { code: "missing_parameter" });
274
372
  return { [parent.column]: value };
275
373
  }
276
374
  async function assertParentExists(c, parent) {
277
375
  if (!parent?.repo) return;
278
376
  const value = c.params[parent.param];
279
- if (!value) throw new HttpError(400, `missing path parameter '${parent.param}'`);
377
+ if (!value) throw new HttpError(400, `missing path parameter '${parent.param}'`, void 0, { code: "missing_parameter" });
280
378
  if (!await parent.repo.get(value)) throw notFound();
281
379
  }
282
380
  async function fetchOwned(repo, c, opts) {
283
381
  const id = c.params[opts.idParam ?? "id"] ?? "";
284
- if (!id) throw new HttpError(400, `missing path parameter '${opts.idParam ?? "id"}'`);
382
+ if (!id) throw new HttpError(400, `missing path parameter '${opts.idParam ?? "id"}'`, void 0, { code: "missing_parameter" });
285
383
  const row = await repo.get(id);
286
384
  if (!row) throw notFound();
287
385
  if (opts.parent) {
@@ -298,13 +396,15 @@ function mountCrud(app, repo, opts) {
298
396
  const maxLimit = opts.maxLimit ?? 200;
299
397
  if (enabled.has("list")) {
300
398
  app.get(base, async (c) => {
301
- await assertParentExists(c, opts.parent);
399
+ assertKnownKeys(c.query, opts);
302
400
  const where = {};
303
401
  for (const [k, v] of Object.entries(c.query)) {
304
- if (!opts.columns || !(k in opts.columns)) continue;
402
+ if (!opts.columns || !Object.prototype.hasOwnProperty.call(opts.columns, k)) continue;
403
+ assertNoOperator(k, v);
305
404
  if (isJsonColumn(opts.columns[k])) assertJsonFilter(k, v);
306
405
  where[k] = v;
307
406
  }
407
+ await assertParentExists(c, opts.parent);
308
408
  Object.assign(where, parentWhere(c, opts.parent));
309
409
  const limit = Math.min(Math.max(INT(c.query.limit, defaultLimit), 1), maxLimit);
310
410
  const offset = Math.max(INT(c.query.offset, 0), 0);
@@ -338,7 +438,7 @@ function mountCrud(app, repo, opts) {
338
438
  if (enabled.has("update")) {
339
439
  app.put(idTemplate, async (c) => {
340
440
  const { id } = await fetchOwned(repo, c, opts);
341
- if (updateFields(c.body).length === 0) throw new HttpError(400, EMPTY_UPDATE_MESSAGE);
441
+ if (updateFields(c.body).length === 0) throw new HttpError(400, EMPTY_UPDATE_MESSAGE, void 0, { code: "empty_update" });
342
442
  const patch = { ...c.body, ...parentWhere(c, opts.parent) };
343
443
  return c.json(await repo.update(id, patch));
344
444
  });
@@ -353,11 +453,14 @@ function mountCrud(app, repo, opts) {
353
453
  return app;
354
454
  }
355
455
  export {
456
+ ACTOR_HEADERS,
356
457
  DEFAULT_GATEWAY_ENDPOINT,
357
458
  DEFAULT_SETTINGS_ERROR_TTL_MS,
358
459
  DEFAULT_SETTINGS_TIMEOUT_MS,
359
460
  DEFAULT_SETTINGS_TTL_MS,
360
461
  HttpError,
462
+ RESERVED_LIST_QUERY_KEYS,
463
+ actorFrom,
361
464
  badRequest,
362
465
  conflict,
363
466
  createApp,