@crombolo/backoffice-host 0.36.2 → 0.38.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crombolo/backoffice-host",
3
- "version": "0.36.2",
3
+ "version": "0.38.1",
4
4
  "description": "Internal to crombolo, with no compatibility promise: use @crombolo/crombolo. Serves the Umbraco backoffice SPA: shell HTML, import map and package manifests.",
5
5
  "license": "MIT",
6
6
  "author": "Crombolo",
@@ -19,7 +19,8 @@
19
19
  "type": "module",
20
20
  "exports": {
21
21
  ".": "./src/index.ts",
22
- "./branding": "./src/branding.ts"
22
+ "./branding": "./src/branding.ts",
23
+ "./registry": "./src/registry.ts"
23
24
  },
24
25
  "files": [
25
26
  "assets",
@@ -31,7 +32,7 @@
31
32
  "access": "public"
32
33
  },
33
34
  "dependencies": {
34
- "@crombolo/core": "0.36.2",
35
+ "@crombolo/core": "0.38.1",
35
36
  "@crombolo/backoffice-dist": "18.2.0"
36
37
  }
37
38
  }
@@ -2,7 +2,7 @@
2
2
  "$schema": "../../../backoffice-dist/dist/umbraco-package-schema.json",
3
3
  "name": "Crombolo App Preview",
4
4
  "id": "Crombolo.AppPreview",
5
- "version": "0.36.2",
5
+ "version": "0.38.1",
6
6
  "allowPublicAccess": false,
7
7
  "extensions": [
8
8
  {
@@ -27,12 +27,25 @@ export const searchMarketplace = (query) =>
27
27
 
28
28
  export const listInstalled = () => json('/installed')
29
29
 
30
- export const installBundle = (name, version, applyContent = true, acceptServerCode = false) =>
30
+ export const installBundle = (
31
+ name,
32
+ version,
33
+ applyContent = true,
34
+ acceptServerCode = false,
35
+ grant = [],
36
+ ) =>
31
37
  json('/install', {
32
38
  method: 'POST',
33
- body: JSON.stringify({ name, version, applyContent, acceptServerCode }),
39
+ body: JSON.stringify({ name, version, applyContent, acceptServerCode, grant }),
34
40
  })
35
41
 
42
+ /** Approves everything an installed bundle asks to do, turning it on (story 222). */
43
+ export const grantBundle = (id) => json('/grant', { method: 'POST', body: JSON.stringify({ id }) })
44
+
45
+ /** Withdraws a bundle's approval, turning it off. */
46
+ export const withdrawBundle = (id) =>
47
+ json('/withdraw', { method: 'POST', body: JSON.stringify({ id }) })
48
+
36
49
  export const uninstallBundle = (name) =>
37
50
  json('/uninstall', { method: 'POST', body: JSON.stringify({ name }) })
38
51
 
@@ -17,7 +17,7 @@
17
17
  import { css, html, nothing, repeat } from '@umbraco-cms/backoffice/external/lit'
18
18
  import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'
19
19
  import { carriesTags } from './bundles-carries.js'
20
- import { listInstalled, uninstallBundle } from './bundles-client.js'
20
+ import { grantBundle, listInstalled, uninstallBundle, withdrawBundle } from './bundles-client.js'
21
21
 
22
22
  /** Where each part of a bundle stands on this site, in the words of someone running it. */
23
23
  function status(item) {
@@ -30,9 +30,11 @@ function status(item) {
30
30
  )
31
31
  if (item.carries?.server)
32
32
  parts.push(
33
- item.wired
34
- ? html`<span>Server features on</span>`
35
- : html`<span>Server features off until the site's configuration includes it</span>`,
33
+ !item.on
34
+ ? html`<span>Off until what it asks to do is approved</span>`
35
+ : item.wired
36
+ ? html`<span>Server features on</span>`
37
+ : html`<span>Server features off until the site's configuration includes it</span>`,
36
38
  )
37
39
  return parts.length > 0 ? parts : html`<span>Ready</span>`
38
40
  }
@@ -92,6 +94,74 @@ export default class CromboloBundlesInstalledElement extends UmbLitElement {
92
94
  }
93
95
  }
94
96
 
97
+ /** Approves everything it asks to do, or withdraws that, turning it on or off (story 222). */
98
+ async #setGrant(item, grant) {
99
+ this._busy = item.packageName
100
+ try {
101
+ const outcome = grant ? await grantBundle(item.id) : await withdrawBundle(item.id)
102
+ this._notice = outcome.message ?? ''
103
+ if (outcome.ok) await this.#load()
104
+ } catch (error) {
105
+ this._notice = error instanceof Error ? error.message : String(error)
106
+ } finally {
107
+ this._busy = ''
108
+ }
109
+ }
110
+
111
+ /** What it may do with the site, and the button that approves or withdraws it. */
112
+ #permissions(item) {
113
+ if (!item.carries?.server) return nothing
114
+ const asks = item.permissions ?? []
115
+ return html`
116
+ <h4>What it may do</h4>
117
+ ${
118
+ asks.length === 0
119
+ ? html`<p>Nothing beyond its own data: it asks for no access to the site's content, members or settings.</p>`
120
+ : html`<ul class="asks">
121
+ ${asks.map(
122
+ (ask) =>
123
+ html`<li class=${(item.missing ?? []).includes(ask.permission) ? 'waiting' : ''}>
124
+ ${ask.allows}
125
+ </li>`,
126
+ )}
127
+ </ul>`
128
+ }
129
+ ${
130
+ item.on
131
+ ? html`<p class="note">
132
+ ${
133
+ item.granted
134
+ ? `Approved${item.granted.by ? ` by ${item.granted.by}` : ''} on ${new Date(item.granted.at).toLocaleDateString()}.`
135
+ : 'Needs no approval.'
136
+ }
137
+ </p>
138
+ ${
139
+ item.granted
140
+ ? html`<uui-button
141
+ look="secondary"
142
+ color="danger"
143
+ label="Withdraw approval"
144
+ .state=${this._busy === item.packageName ? 'waiting' : undefined}
145
+ @click=${() => this.#setGrant(item, false)}></uui-button>`
146
+ : nothing
147
+ }`
148
+ : html`<p class="note">
149
+ ${
150
+ item.granted
151
+ ? 'This version asks for more than was approved, so it is off until you approve all of it.'
152
+ : 'It is off until you approve all of what it asks to do.'
153
+ }
154
+ </p>
155
+ <uui-button
156
+ look="primary"
157
+ color="warning"
158
+ label="Approve and turn on"
159
+ .state=${this._busy === item.packageName ? 'waiting' : undefined}
160
+ @click=${() => this.#setGrant(item, true)}></uui-button>`
161
+ }
162
+ `
163
+ }
164
+
95
165
  #pick(item) {
96
166
  this._selected = item.packageName
97
167
  this.requestUpdate()
@@ -173,6 +243,7 @@ export default class CromboloBundlesInstalledElement extends UmbLitElement {
173
243
  <dt>Works with</dt>
174
244
  <dd>Crombolo ${item.peerRange}</dd>
175
245
  </dl>
246
+ ${this.#permissions(item)}
176
247
  ${
177
248
  this._installs
178
249
  ? html`<uui-button
@@ -187,6 +258,12 @@ export default class CromboloBundlesInstalledElement extends UmbLitElement {
187
258
  }
188
259
 
189
260
  static styles = css`
261
+ .asks {
262
+ padding-left: 1.25em;
263
+ }
264
+ .asks li.waiting {
265
+ font-weight: 600;
266
+ }
190
267
  :host {
191
268
  display: block;
192
269
  padding: var(--uui-size-layout-1, 24px);
@@ -33,6 +33,7 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
33
33
  _elsewhere: { state: true },
34
34
  _consenting: { state: true },
35
35
  _trusted: { state: true },
36
+ _asks: { state: true },
36
37
  }
37
38
 
38
39
  constructor() {
@@ -51,6 +52,7 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
51
52
  this._elsewhere = null
52
53
  this._consenting = ''
53
54
  this._trusted = false
55
+ this._asks = []
54
56
  }
55
57
 
56
58
  connectedCallback() {
@@ -88,19 +90,21 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
88
90
  }
89
91
 
90
92
  /** Asks first when the bundle runs code on the server; installs otherwise. */
93
+ /** A bundle with server code is asked about first: the server answers with what it asks to do. */
91
94
  #requestInstall(item) {
92
- if (item.carries?.server) this.#askConsent(item)
93
- else this.#install(item, false)
95
+ this.#install(item, false)
94
96
  }
95
97
 
96
- #askConsent(item) {
98
+ #askConsent(item, asks) {
97
99
  this._consenting = item.name
98
100
  this._trusted = false
101
+ this._asks = asks ?? []
99
102
  }
100
103
 
101
104
  #cancelConsent() {
102
105
  this._consenting = ''
103
106
  this._trusted = false
107
+ this._asks = []
104
108
  }
105
109
 
106
110
  async #install(item, acceptServerCode) {
@@ -112,12 +116,13 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
112
116
  item.version,
113
117
  !this._declined.has(item.name),
114
118
  acceptServerCode,
119
+ acceptServerCode ? this._asks.map((ask) => ask.permission) : [],
115
120
  )
116
- // The version that would install may have gained server code since the
117
- // list was read: the server says so, and the card asks.
118
- if (outcome.needsServerConsent && !acceptServerCode) {
119
- this._notice = outcome.message ?? ''
120
- this.#askConsent({ ...item, carries: { ...item.carries, server: true } })
121
+ // Server code, or a version that asks for more than was approved: the
122
+ // server says what it asks to do, and the card asks.
123
+ if (outcome.needsServerConsent) {
124
+ if (acceptServerCode) this._notice = outcome.message ?? ''
125
+ this.#askConsent(item, outcome.permissions)
121
126
  return
122
127
  }
123
128
  this._consenting = ''
@@ -163,6 +168,14 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
163
168
  <strong>This bundle runs code on the server.</strong> Once your site's developers turn
164
169
  it on, its code can read and change the site's data, files and settings.
165
170
  </p>
171
+ ${
172
+ this._asks.length > 0
173
+ ? html`<p>It asks to:</p>
174
+ <ul class="asks">
175
+ ${this._asks.map((ask) => html`<li>${ask.allows}</li>`)}
176
+ </ul>`
177
+ : html`<p>It asks for no access to the site's content, members or settings.</p>`
178
+ }
166
179
  <p class="meta">
167
180
  <span>Published by ${item.publisher ?? 'an unnamed publisher'}</span>
168
181
  <a href=${item.links.npm} target="_blank" rel="noopener">npm</a>
@@ -173,7 +186,7 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
173
186
  }
174
187
  </p>
175
188
  <uui-checkbox
176
- label="I trust this publisher with the site's server"
189
+ label="I trust this publisher, and approve what it asks to do"
177
190
  .checked=${this._trusted}
178
191
  @change=${(event) => {
179
192
  this._trusted = event.target.checked
@@ -182,7 +195,7 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
182
195
  <uui-button
183
196
  look="primary"
184
197
  color="warning"
185
- label="Install server code"
198
+ label="Approve and install"
186
199
  ?disabled=${!this._trusted}
187
200
  .state=${this._busy === item.name ? 'waiting' : undefined}
188
201
  @click=${() => this.#install(item, true)}></uui-button>
@@ -332,6 +345,10 @@ export default class CromboloBundlesMarketplaceElement extends UmbLitElement {
332
345
  border-left: 3px solid var(--uui-color-warning, #f0ac00);
333
346
  background: var(--uui-color-surface-alt, #f3f3f5);
334
347
  }
348
+ .consent .asks {
349
+ margin: 0 0 var(--uui-size-space-3, 9px);
350
+ padding-left: 1.25em;
351
+ }
335
352
  .consent .actions {
336
353
  display: flex;
337
354
  gap: var(--uui-size-space-3, 9px);
@@ -0,0 +1,238 @@
1
+ /**
2
+ * The Background jobs dashboard in Settings (story 187): the site's and its
3
+ * bundles' jobs, newest first, filtered by state, each with how far it got and
4
+ * why it failed, and a failed one run again by hand.
5
+ */
6
+ import { css, html, LitElement, nothing } from '@umbraco-cms/backoffice/external/lit'
7
+
8
+ const PAGE_SIZE = 50
9
+
10
+ const STATES = [
11
+ ['', 'Everything'],
12
+ ['queued', 'Waiting'],
13
+ ['running', 'Running'],
14
+ ['failed', 'Failed'],
15
+ ['succeeded', 'Done'],
16
+ ]
17
+
18
+ const STATE_LABELS = { queued: 'Waiting', running: 'Running', failed: 'Failed', succeeded: 'Done' }
19
+
20
+ function apiBase() {
21
+ const base = document.querySelector('base')?.getAttribute('href') ?? '/umbraco/'
22
+ return `${base.replace(/\/$/, '')}/crombolo/api/jobs`
23
+ }
24
+
25
+ async function call(path, init, params) {
26
+ const query = params ? `?${new URLSearchParams(params)}` : ''
27
+ const response = await fetch(`${apiBase()}${path}${query}`, {
28
+ credentials: 'include',
29
+ headers: { accept: 'application/json' },
30
+ ...init,
31
+ })
32
+ const body = await response.json().catch(() => ({}))
33
+ if (!response.ok && response.status !== 409)
34
+ throw new Error(`The background jobs could not be read (${response.status}).`)
35
+ return body
36
+ }
37
+
38
+ const when = (iso) => (iso ? new Date(iso).toLocaleString() : '—')
39
+ const owner = (job) => (job.owner === 'site' ? 'The site' : job.owner)
40
+
41
+ function progressOf(job) {
42
+ const p = job.progress
43
+ if (!p) return '—'
44
+ const count = p.total ? `${p.done} of ${p.total}` : `${p.done}`
45
+ return p.note ? `${count}: ${p.note}` : count
46
+ }
47
+
48
+ export default class CromboloJobsDashboardElement extends LitElement {
49
+ static properties = {
50
+ _items: { state: true },
51
+ _total: { state: true },
52
+ _state: { state: true },
53
+ _skip: { state: true },
54
+ _loading: { state: true },
55
+ _notice: { state: true },
56
+ _busy: { state: true },
57
+ _waiting: { state: true },
58
+ }
59
+
60
+ constructor() {
61
+ super()
62
+ this._items = []
63
+ this._total = 0
64
+ this._state = ''
65
+ this._skip = 0
66
+ this._loading = true
67
+ this._notice = ''
68
+ this._busy = ''
69
+ this._waiting = false
70
+ }
71
+
72
+ connectedCallback() {
73
+ super.connectedCallback()
74
+ this.#load()
75
+ }
76
+
77
+ async #load() {
78
+ this._loading = true
79
+ try {
80
+ const params = { skip: String(this._skip), take: String(PAGE_SIZE) }
81
+ if (this._state) params.state = this._state
82
+ const result = await call('', undefined, params)
83
+ this._items = result.items ?? []
84
+ this._total = result.total ?? 0
85
+ this._waiting = Boolean(result.waitingSince)
86
+ } catch (error) {
87
+ this._notice = error instanceof Error ? error.message : String(error)
88
+ } finally {
89
+ this._loading = false
90
+ }
91
+ }
92
+
93
+ async #retry(job) {
94
+ this._busy = job.id
95
+ try {
96
+ const outcome = await call(`/${job.id}/retry`, { method: 'POST' })
97
+ this._notice = outcome.message ?? ''
98
+ await this.#load()
99
+ } catch (error) {
100
+ this._notice = error instanceof Error ? error.message : String(error)
101
+ } finally {
102
+ this._busy = ''
103
+ }
104
+ }
105
+
106
+ #filter(state) {
107
+ this._state = state
108
+ this._skip = 0
109
+ this.#load()
110
+ }
111
+
112
+ #page(by) {
113
+ this._skip = Math.max(0, this._skip + by)
114
+ this.#load()
115
+ }
116
+
117
+ render() {
118
+ return html`
119
+ <p class="intro">
120
+ Work the site and its bundles run in the background: imports, exports, scheduled tasks.
121
+ A job that fails is tried again a few times, then waits here to be run again.
122
+ </p>
123
+ ${
124
+ this._waiting
125
+ ? html`<div class="waiting" role="alert">
126
+ Background work is waiting: nothing is running it. Queued jobs, scheduled
127
+ publishing and notifications will go out once the site's background worker is
128
+ running again.
129
+ </div>`
130
+ : nothing
131
+ }
132
+ ${this._notice ? html`<div class="notice" role="status">${this._notice}</div>` : nothing}
133
+ <div class="filters">
134
+ <uui-select
135
+ label="State"
136
+ .options=${STATES.map(([value, name]) => ({ value, name, selected: value === this._state }))}
137
+ @change=${(event) => this.#filter(event.target.value)}></uui-select>
138
+ </div>
139
+ ${
140
+ this._loading
141
+ ? html`<uui-loader></uui-loader>`
142
+ : this._items.length === 0
143
+ ? html`<uui-box><p>No background jobs${this._state ? ' in this state' : ''}.</p></uui-box>`
144
+ : html`<uui-table aria-label="Background jobs">
145
+ <uui-table-head>
146
+ <uui-table-head-cell>Job</uui-table-head-cell>
147
+ <uui-table-head-cell>From</uui-table-head-cell>
148
+ <uui-table-head-cell>State</uui-table-head-cell>
149
+ <uui-table-head-cell>Progress</uui-table-head-cell>
150
+ <uui-table-head-cell>Queued</uui-table-head-cell>
151
+ <uui-table-head-cell></uui-table-head-cell>
152
+ </uui-table-head>
153
+ ${this._items.map(
154
+ (job) => html`<uui-table-row>
155
+ <uui-table-cell>
156
+ <strong>${job.name}</strong>
157
+ ${job.error ? html`<div class="error">${job.error}</div>` : nothing}
158
+ </uui-table-cell>
159
+ <uui-table-cell>${owner(job)}</uui-table-cell>
160
+ <uui-table-cell>
161
+ ${STATE_LABELS[job.state] ?? job.state}
162
+ <div class="meta">tried ${job.attempts} of ${job.maxAttempts}</div>
163
+ </uui-table-cell>
164
+ <uui-table-cell>${progressOf(job)}</uui-table-cell>
165
+ <uui-table-cell>
166
+ ${when(job.createdAt)}
167
+ ${job.queuedBy ? html`<div class="meta">by ${job.queuedBy}</div>` : nothing}
168
+ </uui-table-cell>
169
+ <uui-table-cell>
170
+ ${
171
+ job.state === 'failed'
172
+ ? html`<uui-button
173
+ look="secondary"
174
+ label="Run again"
175
+ .state=${this._busy === job.id ? 'waiting' : undefined}
176
+ @click=${() => this.#retry(job)}></uui-button>`
177
+ : nothing
178
+ }
179
+ </uui-table-cell>
180
+ </uui-table-row>`,
181
+ )}
182
+ </uui-table>
183
+ <div class="pages">
184
+ <uui-button
185
+ label="Newer"
186
+ ?disabled=${this._skip === 0}
187
+ @click=${() => this.#page(-PAGE_SIZE)}></uui-button>
188
+ <span>${this._skip + 1}–${Math.min(this._skip + PAGE_SIZE, this._total)} of ${this._total}</span>
189
+ <uui-button
190
+ label="Older"
191
+ ?disabled=${this._skip + PAGE_SIZE >= this._total}
192
+ @click=${() => this.#page(PAGE_SIZE)}></uui-button>
193
+ </div>`
194
+ }
195
+ `
196
+ }
197
+
198
+ static styles = css`
199
+ :host {
200
+ display: block;
201
+ padding: var(--uui-size-layout-1);
202
+ }
203
+ .intro {
204
+ margin-top: 0;
205
+ color: var(--uui-color-text-alt);
206
+ }
207
+ .filters {
208
+ margin-bottom: var(--uui-size-space-4);
209
+ }
210
+ .notice {
211
+ margin-bottom: var(--uui-size-space-4);
212
+ }
213
+ .waiting {
214
+ margin-bottom: var(--uui-size-space-4);
215
+ padding: var(--uui-size-space-4);
216
+ border-left: 4px solid var(--uui-color-warning);
217
+ background: var(--uui-color-warning-standalone, var(--uui-color-surface-alt));
218
+ color: var(--uui-color-warning-contrast, inherit);
219
+ }
220
+ .error {
221
+ color: var(--uui-color-danger);
222
+ font-size: 0.9em;
223
+ white-space: pre-wrap;
224
+ }
225
+ .meta {
226
+ color: var(--uui-color-text-alt);
227
+ font-size: 0.85em;
228
+ }
229
+ .pages {
230
+ display: flex;
231
+ align-items: center;
232
+ gap: var(--uui-size-space-4);
233
+ margin-top: var(--uui-size-space-4);
234
+ }
235
+ `
236
+ }
237
+
238
+ customElements.define('crombolo-jobs-dashboard', CromboloJobsDashboardElement)
@@ -2,7 +2,7 @@
2
2
  "$schema": "../../../backoffice-dist/dist/umbraco-package-schema.json",
3
3
  "name": "Crombolo Localizations",
4
4
  "id": "Crombolo.Localizations",
5
- "version": "0.36.2",
5
+ "version": "0.38.1",
6
6
  "allowPublicAccess": true,
7
7
  "extensions": [
8
8
  {
@@ -2,7 +2,7 @@
2
2
  "$schema": "../../../backoffice-dist/dist/umbraco-package-schema.json",
3
3
  "name": "Crombolo Search & sharing",
4
4
  "id": "Crombolo.Seo",
5
- "version": "0.36.2",
5
+ "version": "0.38.1",
6
6
  "allowPublicAccess": false,
7
7
  "extensions": [
8
8
  {
@@ -2,7 +2,7 @@
2
2
  "$schema": "../../../backoffice-dist/dist/umbraco-package-schema.json",
3
3
  "name": "Crombolo Sign-in Dialog",
4
4
  "id": "Crombolo.SignInDialog",
5
- "version": "0.36.2",
5
+ "version": "0.38.1",
6
6
  "allowPublicAccess": true,
7
7
  "extensions": [
8
8
  {
@@ -2,7 +2,7 @@
2
2
  "$schema": "../../backoffice-dist/dist/umbraco-package-schema.json",
3
3
  "name": "Crombolo",
4
4
  "id": "Crombolo.Core",
5
- "version": "0.36.2",
5
+ "version": "0.38.1",
6
6
  "allowPublicAccess": false,
7
7
  "extensions": [
8
8
  {
@@ -241,6 +241,23 @@
241
241
  }
242
242
  ]
243
243
  },
244
+ {
245
+ "type": "dashboard",
246
+ "alias": "Crombolo.Dashboard.BackgroundJobs",
247
+ "name": "Crombolo Background Jobs Dashboard",
248
+ "element": "/crombolo-plugin/jobs-dashboard.js",
249
+ "weight": 3,
250
+ "meta": {
251
+ "label": "Background jobs",
252
+ "pathname": "background-jobs"
253
+ },
254
+ "conditions": [
255
+ {
256
+ "alias": "Umb.Condition.SectionAlias",
257
+ "match": "Umb.Section.Settings"
258
+ }
259
+ ]
260
+ },
244
261
  {
245
262
  "type": "dashboard",
246
263
  "alias": "Crombolo.Dashboard.AuditLog",
@@ -8,6 +8,7 @@
8
8
  */
9
9
  import { existsSync, readFileSync, statSync } from 'node:fs'
10
10
  import { dirname, join, normalize } from 'node:path'
11
+ import { permissionsProblem } from './bundle-permissions.ts'
11
12
  import type { PackageManifestImportmap } from './manifests.ts'
12
13
 
13
14
  /** The package a bundle declares its peer range on. */
@@ -39,13 +40,35 @@ export interface CromboloField {
39
40
  content?: true
40
41
  /** The factory the package exports for the server half. Never imported by core. */
41
42
  server?: string
43
+ /**
44
+ * The bundle schema its server half is written for; absent means 1. This
45
+ * release reads `BUNDLE_SCHEMA_VERSION`.
46
+ */
47
+ schemaVersion?: number
42
48
  /**
43
49
  * What this release's table steps promise a running site, for a bundle that
44
50
  * owns tables: `breaking` exactly when it ships a contract.
45
51
  */
46
52
  migrations?: 'compatible' | 'breaking'
53
+ /**
54
+ * Under an anonymised export, each of its tables that may travel, and how
55
+ * (story 189): `keep`, or its columns as `member`, `email` or `scrub`. A
56
+ * table it does not name travels empty.
57
+ */
58
+ anonymise?: Record<string, 'keep' | Record<string, 'member' | 'email' | 'scrub'>>
59
+ /**
60
+ * What its server half may do with the site (story 222), granted as a whole
61
+ * by an administrator. Required of a server half from schema 3.
62
+ */
63
+ permissions?: string[]
47
64
  }
48
65
 
66
+ /**
67
+ * The bundle schema a server half must be written for: 3 since it declares the
68
+ * permissions it needs (story 222); 2 made its routes route handlers (211).
69
+ */
70
+ export const BUNDLE_SCHEMA_VERSION = 3
71
+
49
72
  /** A bundle as read from its package. */
50
73
  export interface BundlePackage {
51
74
  packageName: string
@@ -92,6 +115,31 @@ export function declaresBundle(json: PackageJson | undefined): boolean {
92
115
  return Boolean(json?.crombolo) && json?.name !== CORE_PACKAGE
93
116
  }
94
117
 
118
+ /** What a server half written for an older schema must change, by the schema it is at. */
119
+ export function schemaProblem(schema: number): string {
120
+ const changes = [
121
+ schema < 2 ? 'its routes are route handlers since 0.37 (docs/bundles.md, "Routes")' : '',
122
+ schema < 3
123
+ ? 'it declares the permissions it needs in "crombolo.permissions" (docs/bundles.md, "Permissions")'
124
+ : '',
125
+ ].filter(Boolean)
126
+ return `its server half is written for bundle schema ${schema}, and this release reads ${BUNDLE_SCHEMA_VERSION}: ${changes.join(', and ')}, with "crombolo.schemaVersion": ${BUNDLE_SCHEMA_VERSION}`
127
+ }
128
+
129
+ const isPlainObject = (value: unknown): value is Record<string, unknown> =>
130
+ Boolean(value) && typeof value === 'object' && !Array.isArray(value)
131
+
132
+ /** The shape of `crombolo.anonymise`; whether its tables and columns exist is the server's to check. */
133
+ function isAnonymiseRules(value: unknown): boolean {
134
+ if (!isPlainObject(value)) return false
135
+ return Object.values(value).every(
136
+ (rule) =>
137
+ rule === 'keep' ||
138
+ (isPlainObject(rule) &&
139
+ Object.values(rule).every((how) => how === 'member' || how === 'email' || how === 'scrub')),
140
+ )
141
+ }
142
+
95
143
  /**
96
144
  * Every reason a package's manifest is not a bundle, reported together.
97
145
  *
@@ -123,8 +171,30 @@ export function validateBundlePackage(json: PackageJson, directory?: string): st
123
171
  problems.push('"crombolo.extensions" must be a list of extension manifests')
124
172
  if (f.migrations !== undefined && f.migrations !== 'compatible' && f.migrations !== 'breaking')
125
173
  problems.push('"crombolo.migrations" is "compatible" or "breaking"')
174
+ if (f.anonymise !== undefined && !isAnonymiseRules(f.anonymise))
175
+ problems.push(
176
+ '"crombolo.anonymise" maps each table to "keep" or to its columns as "member", "email" or "scrub"',
177
+ )
126
178
  if (f.server !== undefined && (typeof f.server !== 'string' || !EXPORT_NAME.test(f.server)))
127
179
  problems.push('"crombolo.server" must name the factory the package exports')
180
+ if (
181
+ f.schemaVersion !== undefined &&
182
+ (!Number.isInteger(f.schemaVersion) || (f.schemaVersion as number) < 1)
183
+ )
184
+ problems.push('"crombolo.schemaVersion" is a whole number')
185
+ else if (
186
+ f.server !== undefined &&
187
+ ((f.schemaVersion as number | undefined) ?? 1) < BUNDLE_SCHEMA_VERSION
188
+ )
189
+ problems.push(schemaProblem((f.schemaVersion as number | undefined) ?? 1))
190
+ if (f.server !== undefined && f.permissions === undefined)
191
+ problems.push(
192
+ 'its server half declares no "crombolo.permissions": list what it may do with the site, [] for nothing (docs/bundles.md, "Permissions")',
193
+ )
194
+ else if (f.permissions !== undefined) {
195
+ const problem = permissionsProblem(f.permissions)
196
+ if (problem) problems.push(problem)
197
+ }
128
198
  if (f.content !== undefined) {
129
199
  if (typeof f.content === 'string')
130
200
  problems.push(
@@ -0,0 +1,44 @@
1
+ /**
2
+ * What a bundle may ask to do with the site (story 222): each permission, and
3
+ * the sentence an administrator reads before granting it. A bundle's package
4
+ * declares the ones it needs in `crombolo.permissions`; an administrator grants
5
+ * the whole list, or the bundle stays off. docs/bundles.md, "Permissions".
6
+ */
7
+
8
+ export const BUNDLE_PERMISSIONS = {
9
+ 'redirects.read': "See the site's redirects",
10
+ 'redirects.write': 'Add, change and remove redirects',
11
+ 'documents.read': "Look up the addresses of the site's pages",
12
+ 'identityProviders.read':
13
+ 'See the sign-in providers the site uses and their settings, never their secrets',
14
+ 'identityProviders.write': "Change administrators' settings for those sign-in providers",
15
+ 'media.read': 'See media in the folders it names',
16
+ 'media.write': 'Add and change media in the folders it names',
17
+ 'member.delegate':
18
+ 'Act for a signed-in member who uses it: what it adds is theirs, and it sees only what they may see',
19
+ } as const
20
+
21
+ export type BundlePermission = keyof typeof BUNDLE_PERMISSIONS
22
+
23
+ export const isBundlePermission = (value: unknown): value is BundlePermission =>
24
+ typeof value === 'string' && Object.hasOwn(BUNDLE_PERMISSIONS, value)
25
+
26
+ /** Each permission with what it lets the bundle do, in the order declared. */
27
+ export function describePermissions(
28
+ permissions: readonly string[],
29
+ ): { permission: string; allows: string }[] {
30
+ return permissions.map((permission) => ({
31
+ permission,
32
+ allows: isBundlePermission(permission) ? BUNDLE_PERMISSIONS[permission] : permission,
33
+ }))
34
+ }
35
+
36
+ /** Why a declared list is not one, or undefined when it is. */
37
+ export function permissionsProblem(value: unknown): string | undefined {
38
+ if (!Array.isArray(value)) return '"crombolo.permissions" must be a list of permissions'
39
+ const unknown = value.filter((permission) => !isBundlePermission(permission))
40
+ if (unknown.length > 0)
41
+ return `"crombolo.permissions" names ${unknown.map((p) => JSON.stringify(p)).join(', ')}, which this release does not offer: ${Object.keys(BUNDLE_PERMISSIONS).join(', ')}`
42
+ if (new Set(value).size !== value.length) return '"crombolo.permissions" names a permission twice'
43
+ return undefined
44
+ }
package/src/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from './bundle-package.ts'
2
+ export * from './bundle-permissions.ts'
2
3
  export * from './extensions.ts'
3
4
  export * from './graphics.ts'
4
5
  export * from './login-assets.ts'
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The site's installed bundles and the back office's paths, without the back
3
+ * office itself. Code that runs without it (the worker, story 223) imports
4
+ * this rather than the package root.
5
+ */
6
+ export * from './bundle-package.ts'
7
+ export * from './bundle-permissions.ts'
8
+ export * from './extensions.ts'
9
+ export type * from './manifests.ts'
10
+ export * from './paths.ts'