@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.
- package/README.md +168 -9
- package/dist/{chunk-2BOFXTTC.js → chunk-73D37ZGB.js} +96 -6
- package/dist/chunk-73D37ZGB.js.map +1 -0
- package/dist/{errors-D7FGkghT.d.cts → errors-BPYDadk4.d.cts} +18 -6
- package/dist/{errors-D7FGkghT.d.ts → errors-BPYDadk4.d.ts} +18 -6
- package/dist/index.cjs +86 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10 -3
- package/dist/index.d.ts +10 -3
- package/dist/index.js +71 -81
- package/dist/index.js.map +1 -1
- package/dist/router/index.cjs +87 -17
- package/dist/router/index.cjs.map +1 -1
- package/dist/router/index.d.cts +135 -4
- package/dist/router/index.d.ts +135 -4
- package/dist/router/index.js +118 -15
- package/dist/router/index.js.map +1 -1
- package/package.json +1 -6
- package/dist/chunk-2BOFXTTC.js.map +0 -1
- package/dist/chunk-TUTGCI5D.js +0 -41
- package/dist/chunk-TUTGCI5D.js.map +0 -1
- package/dist/instrument.cjs +0 -75
- package/dist/instrument.cjs.map +0 -1
- package/dist/instrument.d.cts +0 -26
- package/dist/instrument.d.ts +0 -26
- package/dist/instrument.js +0 -7
- package/dist/instrument.js.map +0 -1
package/dist/router/index.d.cts
CHANGED
|
@@ -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-
|
|
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-
|
|
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
|
-
/**
|
|
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 };
|
package/dist/router/index.d.ts
CHANGED
|
@@ -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-
|
|
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-
|
|
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
|
-
/**
|
|
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 };
|
package/dist/router/index.js
CHANGED
|
@@ -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-
|
|
16
|
-
|
|
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}
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
399
|
+
assertKnownKeys(c.query, opts);
|
|
302
400
|
const where = {};
|
|
303
401
|
for (const [k, v] of Object.entries(c.query)) {
|
|
304
|
-
if (!opts.columns || !(
|
|
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,
|