@workbasehq/core 0.0.0 → 0.1.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 (102) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +4 -0
  3. package/package.json +62 -1
  4. package/src/account-provisioning.ts +24 -0
  5. package/src/admin-forms.tsx +70 -0
  6. package/src/admin-security.ts +63 -0
  7. package/src/admin-ui.tsx +438 -0
  8. package/src/app.ts +115 -0
  9. package/src/audit-event.ts +23 -0
  10. package/src/audit.ts +35 -0
  11. package/src/authorization-api.ts +3 -0
  12. package/src/authorization.ts +135 -0
  13. package/src/authorized-execution.ts +15 -0
  14. package/src/bootstrap.ts +23 -0
  15. package/src/browser-dispatch.ts +19 -0
  16. package/src/calendar-display.ts +26 -0
  17. package/src/capabilities.ts +41 -0
  18. package/src/commands.ts +46 -0
  19. package/src/config-proposal-contract.ts +16 -0
  20. package/src/config-proposals.ts +95 -0
  21. package/src/config-shorthand.ts +200 -0
  22. package/src/config.ts +286 -0
  23. package/src/console-contract.ts +105 -0
  24. package/src/console-contribution.ts +7 -0
  25. package/src/console.ts +84 -0
  26. package/src/crud.ts +146 -0
  27. package/src/crypto.ts +33 -0
  28. package/src/detail-display.ts +59 -0
  29. package/src/detail-layout.ts +17 -0
  30. package/src/errors.ts +3 -0
  31. package/src/event-delivery.ts +76 -0
  32. package/src/events.ts +11 -0
  33. package/src/execution/atomic.ts +70 -0
  34. package/src/execution/compiler.ts +55 -0
  35. package/src/execution/context.ts +100 -0
  36. package/src/execution/d1.ts +46 -0
  37. package/src/execution/errors.ts +21 -0
  38. package/src/execution/index.ts +6 -0
  39. package/src/execution/outbox.ts +8 -0
  40. package/src/execution/permissions.ts +9 -0
  41. package/src/execution/policies.ts +156 -0
  42. package/src/execution/policy-receipts.ts +51 -0
  43. package/src/execution/types.ts +74 -0
  44. package/src/execution/workflow.ts +35 -0
  45. package/src/form-display.ts +36 -0
  46. package/src/idempotency.ts +10 -0
  47. package/src/identity-providers.ts +2 -0
  48. package/src/identity-settings.ts +42 -0
  49. package/src/identity-writes.ts +14 -0
  50. package/src/identity.ts +2 -0
  51. package/src/index.ts +32 -0
  52. package/src/json-csrf.ts +22 -0
  53. package/src/kernel/adapters/tenancy.ts +8 -0
  54. package/src/kernel/audit-port.ts +12 -0
  55. package/src/kernel/builtin-source.ts +34 -0
  56. package/src/kernel/composition.ts +77 -0
  57. package/src/kernel/identity-port.ts +36 -0
  58. package/src/kernel/mail-outbox-port.ts +23 -0
  59. package/src/kernel/migrations.ts +76 -0
  60. package/src/kernel/operation-name.ts +8 -0
  61. package/src/kernel/plugin.ts +92 -0
  62. package/src/kernel/predicate.ts +69 -0
  63. package/src/kernel/registry.ts +198 -0
  64. package/src/kernel/schema-check.ts +13 -0
  65. package/src/logging.ts +21 -0
  66. package/src/migrations/better-auth-schema.ts +2 -0
  67. package/src/migrations/email-delivery-schema.ts +6 -0
  68. package/src/migrations/planner.ts +77 -0
  69. package/src/migrations/schema.ts +85 -0
  70. package/src/migrations/version-contract.ts +28 -0
  71. package/src/migrations/versions.ts +90 -0
  72. package/src/ops-schema.ts +13 -0
  73. package/src/ops.ts +34 -0
  74. package/src/organization-permissions.ts +13 -0
  75. package/src/organization-rules.ts +25 -0
  76. package/src/organizations.ts +43 -0
  77. package/src/plugins.ts +3 -0
  78. package/src/policies.ts +186 -0
  79. package/src/public-schema.ts +65 -0
  80. package/src/query/compiler.ts +395 -0
  81. package/src/query/cursor.ts +43 -0
  82. package/src/query/enum-labels.json +16 -0
  83. package/src/query/enum-values.ts +7 -0
  84. package/src/query/errors.ts +10 -0
  85. package/src/query/executor.ts +118 -0
  86. package/src/query/facade.ts +34 -0
  87. package/src/query/labels.ts +105 -0
  88. package/src/query/limits.ts +8 -0
  89. package/src/query/observability.ts +49 -0
  90. package/src/query/routes.ts +60 -0
  91. package/src/query/schema.ts +216 -0
  92. package/src/query/search.ts +15 -0
  93. package/src/relay.ts +65 -0
  94. package/src/request-timing.ts +71 -0
  95. package/src/schema-compatibility.ts +43 -0
  96. package/src/scope-operations.ts +3 -0
  97. package/src/session-contract.ts +1 -0
  98. package/src/types.ts +30 -0
  99. package/src/worker-fetch.ts +14 -0
  100. package/src/workflow-routes.ts +156 -0
  101. package/src/workflow-runtime.ts +327 -0
  102. package/src/workflow-schema.ts +29 -0
@@ -0,0 +1,105 @@
1
+ import { Q, walk, type ISequelizable } from '@jakub.knejzlik/ts-query'
2
+ import type { InstanceConfig } from '../config'
3
+ import type { KernelRegistry } from '../kernel/registry'
4
+ import type { Scope } from '../types'
5
+
6
+ /** Only configured to-one paths are accepted; callers cannot name arbitrary joins. */
7
+ export function labelPath(config: InstanceConfig, entity: string, key: string) {
8
+ const related = config.ui?.entities?.[entity]?.list?.relatedColumns?.[key]
9
+ let source = entity
10
+ const hops: { source: string; field: string; target: string }[] = []
11
+ for (const field of related ? [related.via, related.field] : [key]) {
12
+ const spec = config.entities[source]?.fields[field]
13
+ if (spec?.type !== 'ref' || !spec.entity) return undefined
14
+ hops.push({ source, field, target: spec.entity }); source = spec.entity
15
+ }
16
+ return { hops, entity: source, display: config.entities[source].displayField }
17
+ }
18
+ export function readableLabel(kernel: KernelRegistry, scope: Scope, entity: string, key: string) {
19
+ const path = labelPath(kernel.config, entity, key)
20
+ if (!path || path.hops.some(hop => !kernel.fieldMask(hop.source, scope).includes(hop.field) || !kernel.can(scope, hop.target, 'read') || !kernel.fieldMask(hop.target, scope).includes('id'))) return undefined
21
+ // Masked display fields produce Record, with a null sorting key.
22
+ return { ...path, display: readableDisplay(kernel, scope, path.entity) }
23
+ }
24
+ export const labelAlias = (key: string) => `__label_${key}`
25
+ export const sortAlias = (key: string) => `__sort_${key}`
26
+
27
+ /** Discover column operands through ts-query's visitor, including operands in Fn.if.
28
+ * Dotted operands are configured to-one FK paths, ending in a real field. A target's
29
+ * displayField expands its entity label in that target's own scoped source.
30
+ */
31
+ const columnCache = new WeakMap<ISequelizable, string[]>()
32
+ export function expressionColumns(expression: ISequelizable): string[] {
33
+ const cached = columnCache.get(expression)
34
+ if (cached) return cached
35
+ const columns = new Set<string>()
36
+ walk(Q.select().field(expression as ReturnType<typeof Q.raw>), {
37
+ onColumn: (table, name) => { columns.add(table ? `${table}.${name}` : name) },
38
+ onRaw: () => { throw new Error('Display labels require structured ts-query expressions, not raw SQL') },
39
+ onSubquery: depth => { if (depth) throw new Error('Display labels use ref paths, not subqueries') },
40
+ })
41
+ const result = [...columns]
42
+ columnCache.set(expression, result)
43
+ return result
44
+ }
45
+ export function expressionPath(config: Pick<InstanceConfig, 'entities'>, entity: string, column: string) {
46
+ const parts = column.split('.')
47
+ const field = parts.pop()!
48
+ const hops: { source: string; field: string; target: string }[] = []
49
+ for (const key of parts) {
50
+ const spec = config.entities[entity]?.fields[key]
51
+ if (spec?.type !== 'ref' || !spec.entity) throw new Error(`Invalid label reference: ${entity}.${column}`)
52
+ hops.push({ source: entity, field: key, target: spec.entity }); entity = spec.entity
53
+ }
54
+ if (!['id', 'organization_id', 'created_at', 'updated_at', 'version'].includes(field) && !Object.hasOwn(config.entities[entity].fields, field)) throw new Error(`Unknown label field: ${entity}.${field}`)
55
+ return { hops, entity, field }
56
+ }
57
+ export function validateLabelExpressions(config: InstanceConfig) {
58
+ function visit(entity: string, stack: string[]) {
59
+ const spec = config.entities[entity]
60
+ if (!spec.label) return
61
+ if (!spec.displayField || spec.fields[spec.displayField]?.type !== 'string' || !spec.fields[spec.displayField]?.readOnly) throw new Error(`Label requires a read-only string displayField: ${entity}`)
62
+ if (stack.includes(entity)) throw new Error(`Cyclic display label: ${[...stack, entity].join(' -> ')}`)
63
+ for (const column of expressionColumns(spec.label)) {
64
+ const path = expressionPath(config, entity, column)
65
+ if (path.field === config.entities[path.entity].displayField) visit(path.entity, [...stack, entity])
66
+ }
67
+ }
68
+ for (const entity of Object.keys(config.entities)) visit(entity, [])
69
+ }
70
+
71
+ /** A label is readable only when every dependency is readable. Never use a persisted
72
+ * value as a fallback when a dependency is masked. Runtime row scopes still apply.
73
+ */
74
+ export function readableDisplay(kernel: KernelRegistry, scope: Scope, entity: string): string | undefined {
75
+ const spec = kernel.config.entities[entity]
76
+ if (!spec.displayField || !kernel.fieldMask(entity, scope).includes(spec.displayField)) return undefined
77
+ if (spec.label && expressionColumns(spec.label).some(column => {
78
+ const path = expressionPath(kernel.config, entity, column)
79
+ return path.hops.some(hop => !kernel.fieldMask(hop.source, scope).includes(hop.field) || !kernel.can(scope, hop.target, 'read') || !kernel.fieldMask(hop.target, scope).includes('id'))
80
+ || !kernel.fieldMask(path.entity, scope).includes(path.field)
81
+ || (path.field === kernel.config.entities[path.entity].displayField && !readableDisplay(kernel, scope, path.entity))
82
+ })) return undefined
83
+ return spec.displayField
84
+ }
85
+
86
+ /** Browser dependency metadata contains field names only; execution stays server-side. */
87
+ export function labelDependencies(config: Pick<InstanceConfig, 'entities'>, entity: string): { entity: string; field: string }[] {
88
+ const result = new Map<string, { entity: string; field: string }>()
89
+ function visit(name: string) {
90
+ const definition = config.entities[name]
91
+ if (!definition.label) return
92
+ for (const column of expressionColumns(definition.label)) {
93
+ const path = expressionPath(config, name, column)
94
+ for (const hop of path.hops) for (const dependency of [{ entity: hop.source, field: hop.field }, { entity: hop.target, field: 'id' }]) result.set(`${dependency.entity}.${dependency.field}`, dependency)
95
+ const dependency = { entity: path.entity, field: path.field }
96
+ const key = `${dependency.entity}.${dependency.field}`
97
+ if (!result.has(key)) {
98
+ result.set(key, dependency)
99
+ if (path.field === config.entities[path.entity].displayField) visit(path.entity)
100
+ }
101
+ }
102
+ }
103
+ visit(entity)
104
+ return [...result.values()]
105
+ }
@@ -0,0 +1,8 @@
1
+ /** ADR 0001 Amendment 1; RFC 0003 findings 9–10. Staging measurement follows in task 5. */
2
+ export const QUERY_LIMITS = Object.freeze({
3
+ root: 100, children: 20, relationDepth: 2, filterDepth: 8, nodes: 400,
4
+ relations: 8, exists: 16, fieldRows: 100_000, parents: 100,
5
+ levelRows: 2_000, rows: 5_000, statements: 16, bindings: 100,
6
+ tableReferences: 64, sqlLength: 64_000, inputBytes: 64_000, cursorBytes: 8_000,
7
+ })
8
+ export interface QueryCost { depth: number; relations: number; fieldRows: number; exists: number; nodes: number }
@@ -0,0 +1,49 @@
1
+ import { ApiError } from '../errors'
2
+ import type { Scope } from '../types'
3
+ import { inputHash } from './cursor'
4
+ import type { QueryCost } from './limits'
5
+ import { databaseIdentity } from '../request-timing'
6
+
7
+ export interface QueryLog {
8
+ queryHash: string
9
+ shape: { entity: string | null; depth: number; relationCount: number; selectCount: number; includeCount: number }
10
+ actorKind: Scope['actor']['type']; tokenId: string | null; organizationId: string
11
+ estimatedCost: QueryCost | null
12
+ bindingCount: number; bindingHighWaterMark: number; statementCount: number
13
+ durationMs: number; resultRows: number; rowsRead: number | null; errorCode: string | null
14
+ }
15
+ export const QUERY_DURATION_SAMPLES = 256
16
+ interface Metrics { queries: number; errors: Record<string, number>; durations: number[]; next: number }
17
+ // Per database handle in this Worker isolate; bounded and deliberately non-durable.
18
+ const metrics = new WeakMap<D1Database, Metrics>()
19
+ export function queryMetrics(db: D1Database) {
20
+ db = databaseIdentity(db)
21
+ const state = metrics.get(db)
22
+ const durations = [...state?.durations ?? []].sort((a, b) => a - b)
23
+ const percentile = (p: number) => durations.length ? durations[Math.ceil(p * durations.length) - 1] : null
24
+ return { queries: state?.queries ?? 0, errors: { ...state?.errors }, durationMs: { samples: durations.length, capacity: QUERY_DURATION_SAMPLES, p50: percentile(.5), p95: percentile(.95) } }
25
+ }
26
+ export function recordQuery(db: D1Database, log: QueryLog) {
27
+ db = databaseIdentity(db)
28
+ let state = metrics.get(db)
29
+ if (!state) { state = { queries: 0, errors: {}, durations: [], next: 0 }; metrics.set(db, state) }
30
+ state.queries++
31
+ if (log.errorCode) state.errors[log.errorCode] = (state.errors[log.errorCode] ?? 0) + 1
32
+ state.durations[state.next] = log.durationMs
33
+ state.next = (state.next + 1) % QUERY_DURATION_SAMPLES
34
+ console.log(JSON.stringify({ event: 'query', ...log }))
35
+ }
36
+ export function emptyQueryLog(scope: Scope, queryHash: string): QueryLog {
37
+ return { queryHash, shape: { entity: null, depth: 0, relationCount: 0, selectCount: 0, includeCount: 0 },
38
+ actorKind: scope.actor.type, tokenId: scope.actor.tokenId ?? null, organizationId: scope.organizationId,
39
+ estimatedCost: null, bindingCount: 0, bindingHighWaterMark: 0, statementCount: 0,
40
+ durationMs: 0, resultRows: 0, rowsRead: null, errorCode: null }
41
+ }
42
+ /** One surface log, including parse/translation errors and REST detail 404s. */
43
+ export async function observeQuery<T>(db: D1Database, scope: Scope, run: (capture: (log: QueryLog) => void, rejectedInput: (input: unknown) => Promise<void>) => Promise<T>): Promise<T> {
44
+ const started = performance.now()
45
+ let log = emptyQueryLog(scope, await inputHash(undefined))
46
+ try { return await run(value => { log = value }, async input => { log.queryHash = await inputHash(input) }) }
47
+ catch (error) { log.errorCode = error instanceof ApiError ? error.code : 'query_invalid'; log.resultRows = 0; throw error }
48
+ finally { log.durationMs = performance.now() - started; recordQuery(db, log) }
49
+ }
@@ -0,0 +1,60 @@
1
+ import { randomToken } from '../crypto'
2
+ import type { App, RuntimeEnv } from '../types'
3
+ import type { KernelRegistry } from '../kernel/registry'
4
+ import { QueryError } from './errors'
5
+ import { QUERY_LIMITS as L } from './limits'
6
+ import { observeQuery } from './observability'
7
+ import { executeQuery } from './executor'
8
+ const ephemeralSecrets = new WeakMap<RuntimeEnv, string>()
9
+ const cursorKeys = new WeakMap<RuntimeEnv, { source: string; key: Promise<string> }>()
10
+ export function cursorSecret(env: RuntimeEnv): Promise<string> {
11
+ const configured = env.IDENTITY?.secret ?? env.BETTER_AUTH_SECRET ?? env.INTERNAL_TOKEN
12
+ let secret = configured ?? ephemeralSecrets.get(env)
13
+ if (!secret) { secret = randomToken(); ephemeralSecrets.set(env, secret) }
14
+ const cached = cursorKeys.get(env)
15
+ if (cached?.source === secret) return cached.key
16
+ const key = deriveCursorKey(secret).catch(error => {
17
+ if (cursorKeys.get(env)?.key === key) cursorKeys.delete(env)
18
+ throw error
19
+ })
20
+ cursorKeys.set(env, { source: secret, key })
21
+ return key
22
+ }
23
+ async function deriveCursorKey(secret: string): Promise<string> {
24
+ const encode = (value: string) => new TextEncoder().encode(value)
25
+ const material = await crypto.subtle.importKey('raw', encode(secret), 'HKDF', false, ['deriveBits'])
26
+ const bits = await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256',
27
+ salt: encode('workbase:query-cursor:hkdf-sha256:v1'), info: encode('workbase:query-cursor:v1'),
28
+ }, material, 256)
29
+ return [...new Uint8Array(bits)].map(byte => byte.toString(16).padStart(2, '0')).join('')
30
+ }
31
+ async function readInput(request: Request): Promise<string> {
32
+ const reader = request.body?.getReader()
33
+ if (!reader) return ''
34
+ const chunks: Uint8Array[] = []; let length = 0
35
+ try {
36
+ for (;;) {
37
+ const { done, value } = await reader.read()
38
+ if (done) break
39
+ length += value.length
40
+ if (length > L.inputBytes) { await reader.cancel(); throw new QueryError('query_too_expensive') }
41
+ chunks.push(value)
42
+ }
43
+ } finally { reader.releaseLock() }
44
+ const bytes = new Uint8Array(length); let offset = 0
45
+ for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length }
46
+ try { return new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes) }
47
+ catch { throw new QueryError('query_invalid') }
48
+ }
49
+ export function queryRoutes(app: App, kernel: KernelRegistry, env: RuntimeEnv) {
50
+ app.post('/query', c => observeQuery(env.DB, c.get('scope'), async (writeLog, rejectedInput) => {
51
+ let text = ''; let input: unknown
52
+ try { text = await readInput(c.req.raw); input = JSON.parse(text) }
53
+ catch (error) {
54
+ const failure = error instanceof QueryError ? error : new QueryError('query_invalid')
55
+ await rejectedInput(text)
56
+ throw failure
57
+ }
58
+ return c.json(await executeQuery(kernel, c.get('scope'), env.DB, await cursorSecret(env), input, { writeLog }))
59
+ }))
60
+ }
@@ -0,0 +1,216 @@
1
+ import { z } from 'zod'
2
+ import { baseFields, type Field, type InstanceConfig } from '../config'
3
+ import type { KernelRegistry } from '../kernel/registry'
4
+ import type { Scope } from '../types'
5
+ import { invalid, QueryError, type QueryPath } from './errors'
6
+ import { QUERY_LIMITS as L, type QueryCost } from './limits'
7
+ import { isRestQuery } from './facade'
8
+ import { labelPath } from './labels'
9
+
10
+ export type Scalar = string | number | boolean | null
11
+ export interface Filter { [key: string]: unknown }
12
+ export interface Order { field: string; dir: 'asc' | 'desc'; label?: boolean }
13
+ export interface Selection { labels?: string[]; select?: string[]; where?: Filter; orderBy?: Order[]; limit?: number; include?: Record<string, Selection> }
14
+ export interface QueryInput extends Selection { contextList?: { entity: string; list: string; id: string }; search?: { text: string; fields: string[]; locale?: 'en' | 'cs' }; labelWhere?: Record<string, { contains: string; locale?: 'en' | 'cs' }>; entity: string; limit: number; cursor?: string }
15
+ export const fieldsFor = (config: InstanceConfig, entity: string) => [...baseFields, ...Object.keys(config.entities[entity].fields)]
16
+ export function fieldType(config: InstanceConfig, entity: string, field: string): Field['type'] {
17
+ return config.entities[entity].fields[field]?.type ?? (field === 'version' ? 'int' : ['created_at', 'updated_at'].includes(field) ? 'datetime' : 'string')
18
+ }
19
+ export function operatorsFor(type: Field['type']) {
20
+ return ['eq', 'ne', 'in', ...(['bool'].includes(type) ? [] : ['lt', 'lte', 'gt', 'gte']),
21
+ ...(['string', 'text'].includes(type) ? ['contains'] : []), 'isNull']
22
+ }
23
+ function valueSchema(config: InstanceConfig, entity: string, field: string, rest: boolean) {
24
+ const type = fieldType(config, entity, field)
25
+ // crud.ts accepted all finite numeric operands (also for int fields), and did
26
+ // not impose the write validator's string lengths on URL filter operands.
27
+ if (rest) return type === 'bool' ? z.boolean() : ['int', 'float'].includes(type) ? z.number().finite() : z.string()
28
+ return type === 'bool' ? z.boolean() : type === 'int' ? z.number().int().safe()
29
+ : type === 'float' ? z.number().finite() : z.string().max(2_000)
30
+ }
31
+ /** Shared client/policy grammar; only trusted configuration enables actor references. */
32
+ export function filterSchema(config: InstanceConfig, rest = false, maxDepth = L.relationDepth as number,
33
+ actorValues?: (type: Field['type']) => z.ZodType) {
34
+ const filters = new Map<string, z.ZodType>()
35
+ function filter(name: string, depth: number): z.ZodType {
36
+ const key = `${name}:${depth}`
37
+ const cached = filters.get(key); if (cached) return cached
38
+ const schema: z.ZodType = z.lazy(() => {
39
+ const shape: Record<string, z.ZodType> = Object.create(null)
40
+ for (const field of fieldsFor(config, name)) {
41
+ const scalar = (valueSchema(config, name, field, rest) as z.ZodType).refine((value: unknown) => !actorValues || typeof value !== 'string' || !value.startsWith('$actor.'), 'Actor values require a declared compatible field'); const value = actorValues ? z.union([scalar, actorValues(fieldType(config, name, field))]) : scalar; const ops: Record<string, z.ZodType> = Object.create(null)
42
+ for (const op of rest ? ['eq', 'lt', 'lte', 'gt', 'gte'] : operatorsFor(fieldType(config, name, field))) ops[op] =
43
+ (op === 'isNull' ? (actorValues ? z.union([z.boolean(), actorValues('bool')]) : z.boolean()) : op === 'in' ? z.array(value.nullable()).max(L.bindings)
44
+ : op === 'eq' || op === 'ne' ? value.nullable() : value).optional()
45
+ shape[field] = z.strictObject(ops).refine(v => Object.keys(v).length > 0).optional()
46
+ }
47
+ if (depth < maxDepth) for (const [relation, r] of Object.entries(config.entities[name].relations)) {
48
+ const child = filter(r.entity, depth + 1)
49
+ shape[relation] = (r.many ? z.union([z.strictObject({ some: child }), z.strictObject({ none: child })]) : child).optional()
50
+ }
51
+ shape.and = z.array(schema).min(1).max(L.nodes).optional()
52
+ shape.or = z.array(schema).min(1).max(L.nodes).optional()
53
+ shape.not = schema.optional()
54
+ return z.strictObject(shape)
55
+ })
56
+ filters.set(key, schema); return schema
57
+ }
58
+ return filter
59
+ }
60
+ /** Generated from the complete model. No library AST/raw/functions are client input. */
61
+ export function querySchema(config: InstanceConfig, entity: string, rest = false) {
62
+ const filter = filterSchema(config, rest)
63
+ function selection(name: string, depth: number, root: boolean): z.ZodType {
64
+ const names = fieldsFor(config, name) as [string, ...string[]]
65
+ const labelNames = [...names.filter(key => labelPath(config, name, key)), ...Object.keys(config.ui?.entities?.[name]?.list?.relatedColumns ?? {})] as [string, ...string[]]
66
+ const shape: Record<string, z.ZodType> = {
67
+ select: z.array(z.enum(names)).min(1).max(names.length).refine(v => new Set(v).size === v.length).optional(),
68
+ where: filter(name, depth).optional(),
69
+ orderBy: z.array(z.strictObject({ field: z.enum(root ? [...new Set([...names, ...labelNames])] as [string, ...string[]] : names), dir: z.enum(['asc', 'desc']), ...(root ? { label: z.boolean().optional() } : {}) })).max(5)
70
+ .refine(v => new Set(v.map(o => o.field)).size === v.length).optional(),
71
+ limit: root ? z.number().int().min(1).max(L.root) : z.number().int().min(1).max(L.children).optional(),
72
+ }
73
+ if (depth < L.relationDepth) shape.include = z.strictObject(Object.fromEntries(Object.entries(config.entities[name].relations)
74
+ .map(([key, r]) => [key, z.lazy(() => selection(r.entity, depth + 1, false)).optional()]))).optional()
75
+ if (root) {
76
+ if (labelNames.length) {
77
+ shape.labelWhere = z.partialRecord(z.enum(labelNames), z.strictObject({ contains: z.string().min(1).max(2000), locale: z.enum(['en', 'cs']).optional() })).optional()
78
+ shape.labels = z.array(z.enum(labelNames)).max(L.relations).refine(v => new Set(v).size === v.length).optional()
79
+ }
80
+ shape.search = z.strictObject({ text: z.string().min(1).max(2000), fields: z.array(z.enum([...new Set([...names, ...labelNames])] as [string, ...string[]])).min(1).max(names.length + labelNames.length).refine(v => new Set(v).size === v.length), locale: z.enum(['en', 'cs']).optional() }).optional()
81
+ shape.contextList = z.strictObject({ entity: z.string().regex(/^[a-z][a-z0-9_]*$/).max(100), list: z.string().regex(/^[a-z][a-z0-9_]*$/).max(100), id: z.string().min(1).max(2000) }).optional()
82
+ shape.entity = z.literal(name); shape.cursor = z.string().min(1).max(L.cursorBytes).optional()
83
+ }
84
+ return z.strictObject(shape)
85
+ }
86
+ return selection(entity, 0, true)
87
+ }
88
+ /** Bound recursion before Zod, including malformed/unrecognized inputs. */
89
+ function preflight(input: unknown) {
90
+ let nodes = 0
91
+ function visit(value: unknown, depth: number) {
92
+ if (++nodes > L.nodes || depth > L.filterDepth * 3) throw new QueryError('query_too_expensive', [], { depth, nodes, relations: 0, exists: 0, fieldRows: 0 })
93
+ if (value && typeof value === 'object') {
94
+ if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) invalid()
95
+ for (const [key, child] of Object.entries(value)) {
96
+ if (['__proto__', 'prototype', 'constructor'].includes(key)) invalid(['?'])
97
+ visit(child, depth + 1)
98
+ }
99
+ }
100
+ }
101
+ visit(input, 0)
102
+ }
103
+ export function validateQuery(kernel: KernelRegistry, scope: Scope, input: unknown, legacyErrors = false): { query: QueryInput; cost: QueryCost } {
104
+ preflight(input)
105
+ if (!input || typeof input !== 'object' || Array.isArray(input)) invalid()
106
+ const entity = (input as QueryInput).entity
107
+ if (typeof entity !== 'string' || !Object.hasOwn(kernel.config.entities, entity)) throw new QueryError('entity_not_found', ['entity'])
108
+ const depthCost: QueryCost = { depth: 0, relations: 0, fieldRows: 0, exists: 0, nodes: 0 }
109
+ function relationDepth(name: string, node: unknown, depth: number, path: QueryPath) {
110
+ depthCost.nodes++; depthCost.depth = Math.max(depthCost.depth, depth)
111
+ if (depth > L.relationDepth) throw new QueryError('query_too_expensive', path, depthCost)
112
+ if (!node || typeof node !== 'object') return
113
+ for (const [key, child] of Object.entries(node)) {
114
+ if (Object.hasOwn(kernel.config.entities[name].relations, key)) {
115
+ const r = kernel.config.entities[name].relations[key]; depthCost.relations++
116
+ relationDepth(r.entity, child, depth + 1, [...path, key])
117
+ } else if (['where', 'include', 'and', 'or', 'not', 'some', 'none'].includes(key)) {
118
+ if (Array.isArray(child)) child.forEach((item, i) => relationDepth(name, item, depth, [...path, key, i]))
119
+ else relationDepth(name, child, depth, [...path, key])
120
+ }
121
+ }
122
+ }
123
+ relationDepth(entity, input, 0, [])
124
+ const parsed = querySchema(kernel.config, entity, isRestQuery(input)).safeParse(input)
125
+ if (!parsed.success) {
126
+ const issue = parsed.error.issues[0]
127
+ // Unknown client keys/values never become error text or paths.
128
+ const known = new Set(['entity', 'select', 'where', 'search', 'text', 'fields', 'locale', 'labelWhere', 'labels', 'label', 'orderBy', 'field', 'dir', 'limit', 'cursor', 'include', 'and', 'or', 'not', 'some', 'none',
129
+ ...Object.values(kernel.config.entities).flatMap(e => [...Object.keys(e.fields), ...Object.keys(e.relations)]), ...baseFields,
130
+ ...operatorsFor('string')])
131
+ invalid(issue.path.map(p => typeof p === 'number' ? p : known.has(String(p)) ? String(p) : '?'))
132
+ }
133
+ const query = parsed.data as QueryInput
134
+ if (query.contextList) {
135
+ const context = query.contextList
136
+ // Resolve from trusted configuration using the same plugin-over-model precedence as the registry.
137
+ let detail = kernel.config.ui?.entities?.[context.entity]?.detail
138
+ for (const plugin of kernel.config.plugins ?? []) detail = plugin.contributes?.console?.entities?.[context.entity]?.detail ?? detail
139
+ const list = detail?.lists?.[context.list]
140
+ if (!list || !Object.hasOwn(detail!.lists!, context.list) || list.entity !== entity || query.include && Object.keys(query.include).length) throw new QueryError('query_invalid', ['contextList'])
141
+ try { kernel.readPermission(scope, context.entity) } catch { throw new QueryError('field_forbidden', ['contextList']) }
142
+ if (!kernel.fieldMask(context.entity, scope).includes('id')) throw new QueryError('field_forbidden', ['contextList'])
143
+ const locked = { [list.bind.field]: { eq: context.id } }
144
+ query.where = query.where ? { and: [locked, query.where] } : locked
145
+ // This predicate goes through normal field masks, policy-scoped sources and cursor hashing.
146
+ delete query.contextList
147
+ }
148
+ const cost: QueryCost = { depth: 0, relations: 0, fieldRows: 0, exists: 0, nodes: 0 }
149
+ // Every compiled client table source masks each readable FK once. Visibility
150
+ // probes only test the target's scoped predicate, so do not recursively mask it.
151
+ function foreignKeyCost(name: string) {
152
+ cost.exists += kernel.fieldMask(name, scope).filter(field => kernel.config.entities[name].fields[field]?.type === 'ref').length
153
+ }
154
+ function readable(name: string, field: string, path: QueryPath) {
155
+ if (!kernel.fieldMask(name, scope).includes(field)) throw new QueryError('field_forbidden', path)
156
+ }
157
+ function permission(name: string, path: QueryPath) {
158
+ try { kernel.readPermission(scope, name) } catch (error) { if (legacyErrors) throw error; throw new QueryError(path.length ? 'relation_forbidden' : 'field_forbidden', path) }
159
+ }
160
+ function relation(name: string, key: string, path: QueryPath) {
161
+ const r = kernel.config.entities[name].relations[key]
162
+ const fkEntity = r.many ? r.entity : name
163
+ if (!kernel.fieldMask(fkEntity, scope).includes(r.field) || !kernel.fieldMask(r.entity, scope).includes('id')) throw new QueryError('relation_forbidden', path)
164
+ permission(r.entity, path); cost.relations++; return r
165
+ }
166
+ function where(name: string, node: Filter, depth: number, path: QueryPath, nesting = 0) {
167
+ cost.nodes++; cost.depth = Math.max(cost.depth, depth)
168
+ if (nesting > L.filterDepth) throw new QueryError('query_too_expensive', path, cost)
169
+ for (const [key, value] of Object.entries(node)) {
170
+ if (key === 'and' || key === 'or') (value as Filter[]).forEach((v, i) => where(name, v, depth, [...path, key, i], nesting + 1))
171
+ else if (key === 'not') where(name, value as Filter, depth, [...path, key], nesting + 1)
172
+ else if (Object.hasOwn(kernel.config.entities[name].relations, key)) {
173
+ const r = relation(name, key, [...path, key]); cost.exists++
174
+ foreignKeyCost(r.entity)
175
+ const quantifier = r.many ? Object.keys(value as object)[0] : undefined
176
+ where(r.entity, (quantifier ? (value as Record<string, Filter>)[quantifier] : value) as Filter, depth + 1,
177
+ [...path, key, ...(quantifier ? [quantifier] : [])], nesting + 1)
178
+ } else readable(name, key, [...path, key])
179
+ }
180
+ }
181
+ function selection(name: string, node: Selection, depth: number, parents: number, path: QueryPath, single = false) {
182
+ foreignKeyCost(name)
183
+ permission(name, path); cost.depth = Math.max(cost.depth, depth)
184
+ const limit = single ? 1 : node.limit ?? L.children
185
+ const fields = node.select ?? kernel.fieldMask(name, scope)
186
+ fields.forEach((f, i) => readable(name, f, [...path, 'select', i]))
187
+ // Stable ordering, cursor keys and relation assembly all require readable id.
188
+ readable(name, 'id', [...path, 'orderBy'])
189
+ const labelKeys = [...new Set([...(node.labels ?? []), ...Object.keys((node as QueryInput).labelWhere ?? {}), ...((node as QueryInput).search?.fields ?? []).filter(key => labelPath(kernel.config, name, key)), ...(node.orderBy ?? []).filter(o => o.label).map(o => o.field)])]
190
+ const joinedPaths = new Set<string>()
191
+ for (const key of labelKeys) {
192
+ const plan = labelPath(kernel.config, name, key)
193
+ if (!plan) return invalid([...path, 'labels'])
194
+ readable(name, plan.hops[0].field, [...path, 'labels'])
195
+ cost.depth = Math.max(cost.depth, depth + plan.hops.length)
196
+ let joinedPath = ''
197
+ for (const hop of plan.hops) {
198
+ joinedPath += `/${hop.field}`
199
+ if (!joinedPaths.has(joinedPath)) { joinedPaths.add(joinedPath); cost.relations++; foreignKeyCost(hop.target) }
200
+ }
201
+ cost.fieldRows += parents * limit * 2
202
+ }
203
+ for (const key of (node as QueryInput).search?.fields ?? []) if (!labelPath(kernel.config, name, key)) readable(name, key, [...path, 'search', 'fields'])
204
+ node.orderBy?.forEach((o, i) => { if (!o.label) readable(name, o.field, [...path, 'orderBy', i, 'field']) })
205
+ cost.fieldRows += parents * limit * fields.length
206
+ if (node.where) where(name, node.where, depth, [...path, 'where'])
207
+ for (const [key, child] of Object.entries(node.include ?? {})) {
208
+ const r = relation(name, key, [...path, 'include', key])
209
+ selection(r.entity, child, depth + 1, parents * limit, [...path, 'include', key], !r.many)
210
+ }
211
+ }
212
+ selection(entity, query, 0, 1, [])
213
+ if (cost.depth > L.relationDepth || cost.relations > L.relations || cost.exists > L.exists || cost.fieldRows > L.fieldRows || cost.nodes > L.nodes)
214
+ throw new QueryError('query_too_expensive', [], cost)
215
+ return { query, cost }
216
+ }
@@ -0,0 +1,15 @@
1
+ import catalogs from './enum-labels.json'
2
+ const booleanLabels = { en: { yes: 'Yes', no: 'No' }, cs: { yes: 'Ano', no: 'Ne' } }
3
+
4
+ /** Shared enum copy. Context precedes the generic value key, just like i18next. */
5
+ export function valueLabel(config: { enumLabels?: Record<string, Record<string, string>> }, entity: string, key: string, locale = 'en') {
6
+ const language = locale.startsWith('cs') ? 'cs' : 'en'
7
+ const base: Record<string, string> = { ...catalogs[language], ...booleanLabels[language] }
8
+ const overrides: Record<string, string> = config.enumLabels?.[language] ?? {}
9
+ return overrides[`${key}_${entity}`] ?? overrides[key] ?? base[`${key}_${entity}`] ?? base[key] ?? key
10
+ }
11
+
12
+ export function enumLabel(config: { enumLabels?: Record<string, Record<string, string>> }, entity: string, value: string, locale = 'en') {
13
+ const key = `value_${value}`; const label = valueLabel(config, entity, key, locale)
14
+ return label === key ? value : label
15
+ }
package/src/relay.ts ADDED
@@ -0,0 +1,65 @@
1
+ import { boundKernel, KernelRegistry } from './kernel/registry'
2
+ import type { InstanceConfig } from './config'
3
+ import { runWorkflows, type WorkflowRegistry } from './workflow-runtime'
4
+ import type { RuntimeEnv } from './types'
5
+ import type { AuditRelayOptions } from './kernel/audit-port'
6
+ export type WebhookFetch = (url: string, init: RequestInit) => Promise<Response>
7
+ const backoff = [1000, 5000, 30000, 30000]
8
+ export async function dispatchWebhooks(env: RuntimeEnv, options: { now?: number; fetcher?: WebhookFetch } = {}) {
9
+ const now = options.now ?? Date.now(); const timestamp = new Date(now).toISOString()
10
+ // A crash during the final claimed attempt must eventually become an inspectable failure.
11
+ await env.DB.prepare("UPDATE webhook_deliveries SET state='failed',last_error='delivery_interrupted',lease_until=NULL WHERE state='pending' AND attempts>=5 AND (lease_until IS NULL OR lease_until<=?)").bind(timestamp).run()
12
+ const rows = await env.DB.prepare("SELECT event_id,organization_id,payload FROM webhook_deliveries WHERE state='pending' AND next_attempt_at<=? AND (lease_until IS NULL OR lease_until<=?) ORDER BY next_attempt_at LIMIT 100").bind(timestamp, timestamp).all<{ event_id: string; organization_id: string; payload: string }>()
13
+ let delivered = 0; let failed = 0
14
+ for (const row of rows.results) {
15
+ const lease = new Date(now + 30000).toISOString()
16
+ const claim = await env.DB.prepare("UPDATE webhook_deliveries SET lease_until=?,attempts=attempts+1 WHERE event_id=? AND organization_id=? AND state='pending' AND attempts<5 AND next_attempt_at<=? AND (lease_until IS NULL OR lease_until<=?) RETURNING attempts").bind(lease, row.event_id, row.organization_id, timestamp, timestamp).first<{ attempts: number }>()
17
+ if (!claim) continue
18
+ try {
19
+ if (!env.WEBHOOK_URL) throw new Error('destination_not_configured')
20
+ const url = new URL(env.WEBHOOK_URL)
21
+ const allowedHosts = (env.WEBHOOK_ALLOWED_HOSTS ?? '').split(',').map(h => h.trim().toLowerCase()).filter(Boolean)
22
+ const hostAllowed = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || (allowedHosts.includes(url.hostname.toLowerCase()) && url.protocol === 'https:')
23
+ if (!hostAllowed || !['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('destination_not_allowed')
24
+ // Worker-to-Worker calls on Cloudflare must use a Service Binding (public workers.dev fetches between Workers of one account are blocked); local dev keeps plain fetch.
25
+ const transport = options.fetcher ?? (env.WEBHOOK_SERVICE ? (input: string, init?: RequestInit) => env.WEBHOOK_SERVICE!.fetch(input, init) : fetch)
26
+ const response = await transport(url.href, { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(3000), headers: { 'Content-Type': 'application/json', 'X-Event-Id': row.event_id }, body: row.payload })
27
+ await response.body?.cancel()
28
+ if (!response.ok) throw new Error('receiver_rejected')
29
+ await env.DB.prepare("UPDATE webhook_deliveries SET state='delivered',last_error=NULL,lease_until=NULL WHERE event_id=? AND organization_id=? AND lease_until=?").bind(row.event_id, row.organization_id, lease).run()
30
+ delivered++
31
+ } catch {
32
+ // Never persist fetch exceptions: a URL or response could contain credentials or personal data.
33
+ const terminal = claim.attempts >= 5
34
+ await env.DB.prepare('UPDATE webhook_deliveries SET state=?,last_error=?,next_attempt_at=?,lease_until=NULL WHERE event_id=? AND organization_id=? AND lease_until=?').bind(terminal ? 'failed' : 'pending', 'delivery_failed', new Date(now + backoff[Math.min(claim.attempts - 1, 3)]).toISOString(), row.event_id, row.organization_id, lease).run()
35
+ if (terminal) failed++
36
+ }
37
+ }
38
+ return { delivered, failed }
39
+ }
40
+ export async function relay(env: RuntimeEnv, config: InstanceConfig, options: AuditRelayOptions & { fetcher?: WebhookFetch } = {}) {
41
+ const kernel = boundKernel(config) ?? new KernelRegistry(config)
42
+ const audit = await kernel.audit?.relay(env, options) ?? { delivered: 0, errors: 0 }
43
+ return { audit, webhooks: await dispatchWebhooks(env, options) }
44
+ }
45
+
46
+ // Scheduled invocations dispatch explicitly on cron; other schedules must have their own handler.
47
+ export async function scheduledRelay(event: Pick<ScheduledController, 'cron'>, env: RuntimeEnv, workflows?: { config: InstanceConfig; definitions?: WorkflowRegistry }) {
48
+ if (event.cron !== '*/5 * * * *') return
49
+ const { createLogger } = await import('./logging')
50
+ const { relayMetrics, recordRelayRun } = await import('./ops')
51
+ const log = createLogger({ stage: env.STAGE ?? 'local' })
52
+ try {
53
+ if (!workflows?.config) throw new Error('relay_composition_required')
54
+ const kernel = boundKernel(workflows.config) ?? new KernelRegistry(workflows.config, { workflows: workflows.definitions }, env)
55
+ if (kernel.workflows.size) await runWorkflows(env, kernel.config, kernel.workflows)
56
+ const result = await relay(env, workflows.config, { sweep: true })
57
+ const metrics = { ...(await relayMetrics(env)), delivered: result.audit.delivered, webhookDelivered: result.webhooks.delivered, errors: result.audit.errors }
58
+ await recordRelayRun(env, metrics)
59
+ log('info', 'ops.relay.run', metrics)
60
+ } catch {
61
+ // A single event even when metrics/DB are unavailable. Never log raw errors or event payloads.
62
+ log('error', 'ops.relay.run', { backlog: null, oldestAgeSeconds: null, failed: null, delivered: 0 })
63
+ throw new Error('relay_run_failed')
64
+ }
65
+ }
@@ -0,0 +1,71 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks'
2
+
3
+ interface Trace { started: number; spans: Map<string, number>; roundTrips: number }
4
+ const traces = new AsyncLocalStorage<Trace>()
5
+
6
+ export function timedSync<T>(name: string, run: () => T): T {
7
+ const trace = traces.getStore()
8
+ const start = performance.now()
9
+ try { return run() }
10
+ finally { if (trace) trace.spans.set(name, (trace.spans.get(name) ?? 0) + performance.now() - start) }
11
+ }
12
+
13
+ /** Request-local only. Names are fixed by code; never record SQL, URLs or credentials. */
14
+ export async function timed<T>(name: string, run: () => Promise<T>): Promise<T> {
15
+ const trace = traces.getStore()
16
+ if (!trace) return run()
17
+ const start = performance.now()
18
+ try { return await run() }
19
+ finally { trace.spans.set(name, (trace.spans.get(name) ?? 0) + performance.now() - start) }
20
+ }
21
+
22
+ export async function timeRequest(run: () => Promise<Response>): Promise<Response> {
23
+ if (traces.getStore()) return run()
24
+ const trace: Trace = { started: performance.now(), spans: new Map(), roundTrips: 0 }
25
+ return traces.run(trace, async () => {
26
+ const response = await run()
27
+ const total = performance.now() - trace.started
28
+ const spans = ['bootstrap', 'schema', 'auth', 'scope', 'handler', 'd1'].map(name => `${name};dur=${(trace.spans.get(name) ?? 0).toFixed(2)}`)
29
+ spans.push(`d1_roundtrips;desc="${trace.roundTrips}"`, `total;dur=${total.toFixed(2)}`)
30
+ const headers = new Headers(response.headers)
31
+ headers.set('Server-Timing', spans.join(', '))
32
+ return new Response(response.body, { status: response.status, statusText: response.statusText, headers })
33
+ })
34
+ }
35
+
36
+ const databases = new WeakMap<D1Database, D1Database>()
37
+ const databaseBindings = new WeakMap<D1Database, D1Database>()
38
+ /** Preserve database identity for metrics/provenance shared with non-HTTP callers. */
39
+ export const databaseIdentity = (db: D1Database): D1Database => databaseBindings.get(db) ?? db
40
+ /** Stable adapter identity preserves isolate caches; ALS attributes concurrent I/O to its request. */
41
+ export function timedDatabase(db: D1Database): D1Database {
42
+ const existing = databases.get(db)
43
+ if (existing) return existing
44
+ const originals = new WeakMap<D1PreparedStatement, D1PreparedStatement>()
45
+ const call = <T>(run: () => Promise<T>) => {
46
+ const trace = traces.getStore()
47
+ if (trace) trace.roundTrips++
48
+ return timed('d1', run)
49
+ }
50
+ const statement = (raw: D1PreparedStatement): D1PreparedStatement => {
51
+ const wrapped = new Proxy(raw, { get(target, property) {
52
+ if (property === 'bind') return (...values: unknown[]) => statement(target.bind(...values))
53
+ const value = Reflect.get(target, property)
54
+ if (typeof value !== 'function') return value
55
+ return (...args: unknown[]) => call(() => value.apply(target, args))
56
+ } })
57
+ originals.set(wrapped, raw)
58
+ return wrapped
59
+ }
60
+ const wrapped = new Proxy(db, { get(target, property) {
61
+ if (property === 'prepare') return (sql: string) => statement(target.prepare(sql))
62
+ if (property === 'batch') return (statements: D1PreparedStatement[]) => call(() => target.batch(statements.map(item => originals.get(item) ?? item)))
63
+ const value = Reflect.get(target, property)
64
+ if (typeof value !== 'function') return value
65
+ return (...args: unknown[]) => call(() => value.apply(target, args))
66
+ } })
67
+ databases.set(db, wrapped)
68
+ databases.set(wrapped, wrapped)
69
+ databaseBindings.set(wrapped, db)
70
+ return wrapped
71
+ }