506 lines · 20 KBtext/plain; charset=utf-8
The Coline App SDK: apps, tools, file types and surfaces that run inside Coline workspaces, and public websites with Coline Sites. TypeScript, with an in-memory test workspace. MIT.
| 4 |
| 5 | /** |
| 6 | * The security-contract diff (distribution plan §A0/A4/A6): one shared |
| 7 | * comparison that answers "did the user-visible consent contract expand |
| 8 | * between two versions of an app?". |
| 9 | * |
| 10 | * Three consumers, one implementation: |
| 11 | * - the review queue's delta view (what a reviewer must look at), |
| 12 | * - auto-update eligibility (contract expanded → admin must re-consent), |
| 13 | * - the admin re-consent dialog (renders exactly this delta). |
| 14 | * |
| 15 | * Removals never require re-consent. Expansions of authority always do: |
| 16 | * new permissions, new network hosts, tool-effect escalation, web-tier |
| 17 | * surfaces, external hosting changes, and new outbound webhook events. |
| 18 | */ |
| 19 |
| 20 | export interface ToolEffectChange { |
| 21 | name: string; |
| 22 | /** Null when the tool is new in the next version. */ |
| 23 | previousEffect: ToolEffect | null; |
| 24 | nextEffect: ToolEffect | null; |
| 25 | } |
| 26 |
| 27 | export interface SurfaceTierChange { |
| 28 | /** `home`, `files.<typeKey>.editor`, `files.<typeKey>.preview`, … */ |
| 29 | surface: string; |
| 30 | previousTier: SurfaceTier | null; |
| 31 | nextTier: SurfaceTier | null; |
| 32 | } |
| 33 |
| 34 | export interface ScheduleChange { |
| 35 | id: string; |
| 36 | previousCron: string | null; |
| 37 | nextCron: string | null; |
| 38 | } |
| 39 |
| 40 | export interface HostingChange { |
| 41 | previousDefault: "coline" | "external"; |
| 42 | nextDefault: "coline" | "external"; |
| 43 | /** Capabilities newly routed to the developer's backend. */ |
| 44 | overridesNowExternal: string[]; |
| 45 | previousExternalBaseUrl: string | null; |
| 46 | nextExternalBaseUrl: string | null; |
| 47 | externalBaseUrlChanged: boolean; |
| 48 | } |
| 49 |
| 50 | export type SecurityRiskFlag = |
| 51 | | "network_host_wildcard" |
| 52 | | "gains_external_hosting" |
| 53 | | "external_base_url_changed" |
| 54 | | "gains_destructive_tools" |
| 55 | | "many_destructive_tools" |
| 56 | | "gains_web_surface" |
| 57 | | "broad_permission_growth" |
| 58 | | "unverified_endpoint" |
| 59 | | "gains_site_surface"; |
| 60 |
| 61 | export interface AppSecurityContractDelta { |
| 62 | permissionsAdded: string[]; |
| 63 | permissionsRemoved: string[]; |
| 64 | networkHostsAdded: string[]; |
| 65 | networkHostsRemoved: string[]; |
| 66 | toolEffectsChanged: ToolEffectChange[]; |
| 67 | schedulesChanged: ScheduleChange[]; |
| 68 | surfacesChanged: SurfaceTierChange[]; |
| 69 | webhookEventsAdded: string[]; |
| 70 | webhookEventsRemoved: string[]; |
| 71 | hostingChanged: HostingChange | null; |
| 72 | endpointsAdded: string[]; |
| 73 | endpointsRemoved: string[]; |
| 74 | connectionsAdded: string[]; |
| 75 | connectionsRemoved: string[]; |
| 76 | siteToolsAdded: string[]; |
| 77 | /** Collection actions newly opened to site visitors, as `collection.action`. */ |
| 78 | siteAccessOpened: string[]; |
| 79 | jobsEscalated: string[]; |
| 80 | /** The one boolean auto-update and re-consent key on. */ |
| 81 | requiresReconsent: boolean; |
| 82 | /** Human-readable reasons behind `requiresReconsent`, for UI. */ |
| 83 | reconsentReasons: string[]; |
| 84 | riskFlags: SecurityRiskFlag[]; |
| 85 | } |
| 86 |
| 87 |
| 88 | /** |
| 89 | * Whether `next` grants authority none of `before` had. An effect is two |
| 90 | * things, compared separately: the mutation class it may reach and whether |
| 91 | * it may use the network. (`external` allows network but only write-level |
| 92 | * changes, so external → destructive is an escalation; a single rank where |
| 93 | * external sits above destructive would miss it.) |
| 94 | */ |
| 95 | function effectExceeds(next: ToolEffect, before: readonly ToolEffect[]): boolean { |
| 96 | const ceiling = EFFECT_CEILINGS[next]; |
| 97 | const maxBefore = Math.max(-1, ...before.map((effect) => MUTATION_CLASS_RANK[EFFECT_CEILINGS[effect].maxMutation])); |
| 98 | const networkBefore = before.some((effect) => EFFECT_CEILINGS[effect].allowsNetwork); |
| 99 | return MUTATION_CLASS_RANK[ceiling.maxMutation] > maxBefore || (ceiling.allowsNetwork && !networkBefore); |
| 100 | } |
| 101 |
| 102 | const TIER_RANK: Record<SurfaceTier, number> = { |
| 103 | tree: 0, |
| 104 | react: 1, |
| 105 | web: 2, |
| 106 | }; |
| 107 |
| 108 | function diffStringSets( |
| 109 | previous: readonly string[], |
| 110 | next: readonly string[], |
| 111 | ): { added: string[]; removed: string[] } { |
| 112 | const previousSet = new Set(previous); |
| 113 | const nextSet = new Set(next); |
| 114 | return { |
| 115 | added: [...nextSet].filter((value) => !previousSet.has(value)).sort(), |
| 116 | removed: [...previousSet].filter((value) => !nextSet.has(value)).sort(), |
| 117 | }; |
| 118 | } |
| 119 |
| 120 | function collectSurfaces(manifest: ColineAppManifestV2): Map<string, SurfaceTier> { |
| 121 | const surfaces = new Map<string, SurfaceTier>(); |
| 122 | if (manifest.surfaces.home) { |
| 123 | surfaces.set("home", manifest.surfaces.home.tier); |
| 124 | } |
| 125 | if (manifest.surfaces.site) { |
| 126 | surfaces.set("site", "react"); |
| 127 | } |
| 128 | for (const file of manifest.files) { |
| 129 | for (const [name, surface] of Object.entries(file.surfaces)) { |
| 130 | if (surface && typeof surface === "object" && "tier" in surface) { |
| 131 | surfaces.set(`files.${file.typeKey}.${name}`, surface.tier as SurfaceTier); |
| 132 | } |
| 133 | } |
| 134 | } |
| 135 | return surfaces; |
| 136 | } |
| 137 |
| 138 | function collectToolEffects(manifest: ColineAppManifestV2): Map<string, ToolEffect> { |
| 139 | return new Map(manifest.tools.map((tool) => [tool.name, tool.effect])); |
| 140 | } |
| 141 |
| 142 | function externalOverrideKeys(manifest: ColineAppManifestV2): Set<string> { |
| 143 | return new Set( |
| 144 | Object.entries(manifest.hosting.overrides) |
| 145 | .filter(([, model]) => model === "external") |
| 146 | .map(([key]) => key), |
| 147 | ); |
| 148 | } |
| 149 |
| 150 | /** |
| 151 | * Compare two v2 manifests. Pass `previous: null` for a first version — |
| 152 | * everything counts as added and re-consent is trivially required (the |
| 153 | * install consent dialog covers it). |
| 154 | */ |
| 155 | export function compareAppSecurityContract( |
| 156 | previous: ColineAppManifestV2 | null, |
| 157 | next: ColineAppManifestV2, |
| 158 | ): AppSecurityContractDelta { |
| 159 | const reconsentReasons: string[] = []; |
| 160 | const riskFlags = new Set<SecurityRiskFlag>(); |
| 161 |
| 162 | const previousPermissions = previous?.permissions ?? []; |
| 163 | const permissionDiff = diffStringSets(previousPermissions, next.permissions); |
| 164 | if (permissionDiff.added.length > 0) { |
| 165 | reconsentReasons.push( |
| 166 | `Requests ${permissionDiff.added.length} new permission${permissionDiff.added.length === 1 ? "" : "s"}: ${permissionDiff.added.join(", ")}.`, |
| 167 | ); |
| 168 | if (permissionDiff.added.length >= 3) { |
| 169 | riskFlags.add("broad_permission_growth"); |
| 170 | } |
| 171 | } |
| 172 |
| 173 | const previousHosts = previous?.network.allowedHosts ?? []; |
| 174 | const hostDiff = diffStringSets(previousHosts, next.network.allowedHosts); |
| 175 | if (hostDiff.added.length > 0) { |
| 176 | reconsentReasons.push( |
| 177 | `Can now reach ${hostDiff.added.length} new network host${hostDiff.added.length === 1 ? "" : "s"}: ${hostDiff.added.join(", ")}.`, |
| 178 | ); |
| 179 | } |
| 180 | if (next.network.allowedHosts.some((host) => host.startsWith("*."))) { |
| 181 | riskFlags.add("network_host_wildcard"); |
| 182 | } |
| 183 |
| 184 | // Tool effects: record every change; escalate when a tool gains authority |
| 185 | // it lacked, or a new tool exceeds anything the app could previously do. |
| 186 | const previousTools = previous ? collectToolEffects(previous) : new Map<string, ToolEffect>(); |
| 187 | const nextTools = collectToolEffects(next); |
| 188 | const toolEffectsChanged: ToolEffectChange[] = []; |
| 189 | const previousToolEffects = [...previousTools.values()]; |
| 190 | for (const [name, nextEffect] of nextTools) { |
| 191 | const previousEffect = previousTools.get(name) ?? null; |
| 192 | if (previousEffect === nextEffect) { |
| 193 | continue; |
| 194 | } |
| 195 | toolEffectsChanged.push({ name, previousEffect, nextEffect }); |
| 196 | if (previousEffect !== null && effectExceeds(nextEffect, [previousEffect])) { |
| 197 | reconsentReasons.push( |
| 198 | `Tool "${name}" escalates from ${previousEffect} to ${nextEffect}.`, |
| 199 | ); |
| 200 | } |
| 201 | if (previousEffect === null && previous !== null && effectExceeds(nextEffect, previousToolEffects)) { |
| 202 | reconsentReasons.push( |
| 203 | `New tool "${name}" (${nextEffect}) exceeds anything the app could previously do.`, |
| 204 | ); |
| 205 | } |
| 206 | } |
| 207 | for (const [name, previousEffect] of previousTools) { |
| 208 | if (!nextTools.has(name)) { |
| 209 | toolEffectsChanged.push({ name, previousEffect, nextEffect: null }); |
| 210 | } |
| 211 | } |
| 212 |
| 213 | const previousDestructive = [...previousTools.values()].filter( |
| 214 | (effect) => effect === "destructive", |
| 215 | ).length; |
| 216 | const nextDestructive = [...nextTools.values()].filter( |
| 217 | (effect) => effect === "destructive", |
| 218 | ).length; |
| 219 | if (nextDestructive > 0 && previousDestructive === 0 && previous !== null) { |
| 220 | riskFlags.add("gains_destructive_tools"); |
| 221 | } |
| 222 | if (nextDestructive > 5) { |
| 223 | riskFlags.add("many_destructive_tools"); |
| 224 | } |
| 225 |
| 226 | // Schedules: informational (they run app code as the app principal). |
| 227 | const previousSchedules = new Map( |
| 228 | (previous?.triggers.schedules ?? []).map((schedule) => [schedule.id, schedule.cron]), |
| 229 | ); |
| 230 | const nextSchedules = new Map( |
| 231 | next.triggers.schedules.map((schedule) => [schedule.id, schedule.cron]), |
| 232 | ); |
| 233 | const schedulesChanged: ScheduleChange[] = []; |
| 234 | for (const [id, cron] of nextSchedules) { |
| 235 | const previousCron = previousSchedules.get(id) ?? null; |
| 236 | if (previousCron !== cron) { |
| 237 | schedulesChanged.push({ id, previousCron, nextCron: cron }); |
| 238 | } |
| 239 | } |
| 240 | for (const [id, cron] of previousSchedules) { |
| 241 | if (!nextSchedules.has(id)) { |
| 242 | schedulesChanged.push({ id, previousCron: cron, nextCron: null }); |
| 243 | } |
| 244 | } |
| 245 |
| 246 | // Surfaces: web tier = developer-origin embed = consent-relevant. |
| 247 | const previousSurfaces = previous ? collectSurfaces(previous) : new Map<string, SurfaceTier>(); |
| 248 | const nextSurfaces = collectSurfaces(next); |
| 249 | const surfacesChanged: SurfaceTierChange[] = []; |
| 250 | for (const [surface, nextTier] of nextSurfaces) { |
| 251 | const previousTier = previousSurfaces.get(surface) ?? null; |
| 252 | if (previousTier === nextTier) { |
| 253 | continue; |
| 254 | } |
| 255 | surfacesChanged.push({ surface, previousTier, nextTier }); |
| 256 | const reachesWeb = |
| 257 | nextTier === "web" && (previousTier === null || TIER_RANK[previousTier] < TIER_RANK.web); |
| 258 | if (reachesWeb && previous !== null) { |
| 259 | reconsentReasons.push( |
| 260 | `Surface "${surface}" now embeds pages from the developer's own website.`, |
| 261 | ); |
| 262 | riskFlags.add("gains_web_surface"); |
| 263 | } |
| 264 | } |
| 265 | for (const [surface, previousTier] of previousSurfaces) { |
| 266 | if (!nextSurfaces.has(surface)) { |
| 267 | surfacesChanged.push({ surface, previousTier, nextTier: null }); |
| 268 | } |
| 269 | } |
| 270 |
| 271 | // Webhooks: outbound workspace data to the developer's backend. |
| 272 | const webhookDiff = diffStringSets( |
| 273 | (previous?.triggers.webhooks ?? []).map((webhook) => webhook.event), |
| 274 | next.triggers.webhooks.map((webhook) => webhook.event), |
| 275 | ); |
| 276 | if (webhookDiff.added.length > 0 && previous !== null) { |
| 277 | reconsentReasons.push( |
| 278 | `Subscribes to ${webhookDiff.added.length} new outbound event${webhookDiff.added.length === 1 ? "" : "s"}: ${webhookDiff.added.join(", ")}.`, |
| 279 | ); |
| 280 | } |
| 281 |
| 282 | // Hosting: where the app's code runs and where workspace data flows. |
| 283 | const previousDefault = previous?.hosting.default ?? "coline"; |
| 284 | const nextDefault = next.hosting.default; |
| 285 | const previousExternalKeys = previous ? externalOverrideKeys(previous) : new Set<string>(); |
| 286 | const nextExternalKeys = externalOverrideKeys(next); |
| 287 | const overridesNowExternal = [...nextExternalKeys] |
| 288 | .filter((key) => !previousExternalKeys.has(key)) |
| 289 | .sort(); |
| 290 | const previousBaseUrl = previous?.hosting.external?.baseUrl ?? null; |
| 291 | const nextBaseUrl = next.hosting.external?.baseUrl ?? null; |
| 292 | const externalBaseUrlChanged = |
| 293 | previousBaseUrl !== null && nextBaseUrl !== null && previousBaseUrl !== nextBaseUrl; |
| 294 |
| 295 | let hostingChanged: HostingChange | null = null; |
| 296 | if ( |
| 297 | previousDefault !== nextDefault || |
| 298 | overridesNowExternal.length > 0 || |
| 299 | previousBaseUrl !== nextBaseUrl |
| 300 | ) { |
| 301 | hostingChanged = { |
| 302 | previousDefault, |
| 303 | nextDefault, |
| 304 | overridesNowExternal, |
| 305 | previousExternalBaseUrl: previousBaseUrl, |
| 306 | nextExternalBaseUrl: nextBaseUrl, |
| 307 | externalBaseUrlChanged, |
| 308 | }; |
| 309 | } |
| 310 | if (previous !== null) { |
| 311 | const gainsExternal = |
| 312 | (previousDefault === "coline" && nextDefault === "external") || |
| 313 | overridesNowExternal.length > 0 || |
| 314 | (previousBaseUrl === null && nextBaseUrl !== null); |
| 315 | if (gainsExternal) { |
| 316 | reconsentReasons.push( |
| 317 | "Parts of the app now run on the developer's own infrastructure.", |
| 318 | ); |
| 319 | riskFlags.add("gains_external_hosting"); |
| 320 | } |
| 321 | if (externalBaseUrlChanged) { |
| 322 | reconsentReasons.push( |
| 323 | `The app's external backend moved from ${previousBaseUrl} to ${nextBaseUrl}.`, |
| 324 | ); |
| 325 | riskFlags.add("external_base_url_changed"); |
| 326 | } |
| 327 | } |
| 328 |
| 329 | // Endpoints: new inbound doors into the app. |
| 330 | const endpointDiff = diffStringSets( |
| 331 | (previous?.endpoints ?? []).map((endpoint) => endpoint.id), |
| 332 | next.endpoints.map((endpoint) => endpoint.id), |
| 333 | ); |
| 334 | if (endpointDiff.added.length > 0 && previous !== null) { |
| 335 | reconsentReasons.push( |
| 336 | `Receives requests at ${endpointDiff.added.length} new endpoint${endpointDiff.added.length === 1 ? "" : "s"}: ${endpointDiff.added.join(", ")}.`, |
| 337 | ); |
| 338 | } |
| 339 | // An existing endpoint that drops its signature check, or accepts more |
| 340 | // methods, is a wider door than the one that was approved. |
| 341 | const previousEndpoints = new Map((previous?.endpoints ?? []).map((endpoint) => [endpoint.id, endpoint])); |
| 342 | for (const endpoint of next.endpoints) { |
| 343 | const before = previousEndpoints.get(endpoint.id); |
| 344 | if (!before || previous === null) continue; |
| 345 | if (endpoint.verify.kind === "none" && before.verify.kind !== "none") { |
| 346 | reconsentReasons.push(`Endpoint "${endpoint.id}" no longer verifies who is calling it.`); |
| 347 | } else if (before.verify.kind !== "none" && JSON.stringify(before.verify) !== JSON.stringify(endpoint.verify)) { |
| 348 | // Any other change (HMAC → shared token, dropping a timestamp check) |
| 349 | // can weaken it; adding verification to an open endpoint cannot. |
| 350 | reconsentReasons.push(`Endpoint "${endpoint.id}" changes how callers are verified.`); |
| 351 | } |
| 352 | const methodDiff = diffStringSets(before.methods, endpoint.methods); |
| 353 | if (methodDiff.added.length > 0) { |
| 354 | reconsentReasons.push(`Endpoint "${endpoint.id}" now accepts ${methodDiff.added.join(", ")} requests.`); |
| 355 | } |
| 356 | } |
| 357 | if (next.endpoints.some((endpoint) => endpoint.verify.kind === "none")) { |
| 358 | riskFlags.add("unverified_endpoint"); |
| 359 | } |
| 360 |
| 361 | // Connections: accounts on other services, used on members' behalf. |
| 362 | const previousConnections = new Map( |
| 363 | (previous?.connections ?? []).map((connection) => [connection.key, connection]), |
| 364 | ); |
| 365 | const connectionDiff = diffStringSets( |
| 366 | [...previousConnections.keys()], |
| 367 | next.connections.map((connection) => connection.key), |
| 368 | ); |
| 369 | if (connectionDiff.added.length > 0 && previous !== null) { |
| 370 | reconsentReasons.push(`Asks to connect new accounts: ${connectionDiff.added.join(", ")}.`); |
| 371 | } |
| 372 | for (const connection of next.connections) { |
| 373 | const before = previousConnections.get(connection.key); |
| 374 | if (!before || previous === null) continue; |
| 375 | const scopeDiff = diffStringSets(before.oauth2.scopes, connection.oauth2.scopes); |
| 376 | const connectionHostDiff = diffStringSets(before.hosts, connection.hosts); |
| 377 | if (scopeDiff.added.length > 0 || connectionHostDiff.added.length > 0) { |
| 378 | const details = [ |
| 379 | scopeDiff.added.length > 0 ? `scopes: ${scopeDiff.added.join(", ")}` : null, |
| 380 | connectionHostDiff.added.length > 0 ? `hosts: ${connectionHostDiff.added.join(", ")}` : null, |
| 381 | ].filter(Boolean); |
| 382 | reconsentReasons.push( |
| 383 | `Connection "${connection.key}" requests more access (${details.join("; ")}).`, |
| 384 | ); |
| 385 | } |
| 386 | // The token endpoint receives authorization codes (and so, in effect, |
| 387 | // the account's tokens); moving it or the sign-in page is a new trust. |
| 388 | if ( |
| 389 | before.oauth2.tokenUrl !== connection.oauth2.tokenUrl || |
| 390 | before.oauth2.authorizeUrl !== connection.oauth2.authorizeUrl || |
| 391 | before.oauth2.clientId !== connection.oauth2.clientId |
| 392 | ) { |
| 393 | reconsentReasons.push(`Connection "${connection.key}" signs in through a different service or client.`); |
| 394 | } |
| 395 | if (before.scope !== connection.scope) { |
| 396 | reconsentReasons.push( |
| 397 | connection.scope === "workspace" |
| 398 | ? `Connection "${connection.key}" becomes one shared workspace account.` |
| 399 | : `Connection "${connection.key}" becomes a per-member account.`, |
| 400 | ); |
| 401 | } |
| 402 | } |
| 403 |
| 404 | // Site: what visitors outside the workspace can run and reach. |
| 405 | const siteToolDiff = diffStringSets( |
| 406 | previous?.surfaces.site?.tools ?? [], |
| 407 | next.surfaces.site?.tools ?? [], |
| 408 | ); |
| 409 | // A rule change needs consent unless everyone it lets in was already let |
| 410 | // in. `owner` and `signedIn` don't nest: owners include guests, and |
| 411 | // signed-in visitors include people who don't own the record. |
| 412 | type Subject = "public" | "visitor" | "signedIn" | "owner" | "team"; |
| 413 | const covers = (outer: Subject, inner: Subject) => |
| 414 | outer === inner || inner === "team" || outer === "public" || (outer === "visitor" && inner !== "public"); |
| 415 | const actionSubjects = (manifest: ColineAppManifestV2 | null) => { |
| 416 | const subjects = new Map<string, Subject>(); |
| 417 | for (const [name, declaration] of Object.entries(manifest?.collections ?? {})) { |
| 418 | for (const action of ["read", "create", "update", "delete"] as const) { |
| 419 | subjects.set(`${name}.${action}`, declaration.access?.[action] ?? "team"); |
| 420 | } |
| 421 | } |
| 422 | return subjects; |
| 423 | }; |
| 424 | const previousSubjects = actionSubjects(previous); |
| 425 | const accessDiff = { |
| 426 | added: [...actionSubjects(next)] |
| 427 | .filter(([key, subject]) => !covers(previousSubjects.get(key) ?? "team", subject)) |
| 428 | .map(([key]) => key) |
| 429 | .sort(), |
| 430 | }; |
| 431 | if (previous !== null) { |
| 432 | if (next.surfaces.site && !previous.surfaces.site) { |
| 433 | reconsentReasons.push("Adds a public website people outside the workspace can open."); |
| 434 | riskFlags.add("gains_site_surface"); |
| 435 | } else if (siteToolDiff.added.length > 0) { |
| 436 | reconsentReasons.push(`Site visitors can now run: ${siteToolDiff.added.join(", ")}.`); |
| 437 | } |
| 438 | if (accessDiff.added.length > 0) { |
| 439 | reconsentReasons.push(`Site visitors can now reach: ${accessDiff.added.join(", ")}.`); |
| 440 | } |
| 441 | if (next.surfaces.site?.visitors.signIn && !previous.surfaces.site?.visitors.signIn) { |
| 442 | reconsentReasons.push("Site visitors can now sign in."); |
| 443 | } |
| 444 | const nextUploads = next.surfaces.site?.uploads; |
| 445 | const previousUploads = previous.surfaces.site?.uploads; |
| 446 | if (nextUploads && (!previousUploads || (nextUploads.who === "visitor" && previousUploads.who === "signedIn"))) { |
| 447 | reconsentReasons.push( |
| 448 | nextUploads.who === "visitor" ? "Any site visitor can now upload files." : "Signed-in site visitors can now upload files.", |
| 449 | ); |
| 450 | } |
| 451 | const previousEndpointPaths = new Set((previous.surfaces.site?.endpoints ?? []).map((route) => route.path)); |
| 452 | const newEndpointPaths = (next.surfaces.site?.endpoints ?? []).filter((route) => !previousEndpointPaths.has(route.path)); |
| 453 | if (newEndpointPaths.length > 0) { |
| 454 | reconsentReasons.push(`The site now answers requests at: ${newEndpointPaths.map((route) => route.path).join(", ")}.`); |
| 455 | } |
| 456 | } |
| 457 |
| 458 | // Jobs: background work escalating its effect ceiling, or a new job |
| 459 | // exceeding anything the app (tools or jobs) could previously do. |
| 460 | const previousJobs = new Map((previous?.jobs ?? []).map((job) => [job.name, job.effect])); |
| 461 | const previousAuthority = [...previousToolEffects, ...previousJobs.values()]; |
| 462 | const jobsEscalated: string[] = []; |
| 463 | for (const job of next.jobs) { |
| 464 | const before = previousJobs.get(job.name); |
| 465 | if (before && effectExceeds(job.effect, [before])) { |
| 466 | jobsEscalated.push(job.name); |
| 467 | reconsentReasons.push( |
| 468 | `Background job "${job.name}" escalates from ${before} to ${job.effect}.`, |
| 469 | ); |
| 470 | } else if (!before && previous !== null && effectExceeds(job.effect, previousAuthority)) { |
| 471 | jobsEscalated.push(job.name); |
| 472 | reconsentReasons.push( |
| 473 | `New background job "${job.name}" (${job.effect}) exceeds anything the app could previously do.`, |
| 474 | ); |
| 475 | } |
| 476 | } |
| 477 |
| 478 | const requiresReconsent = previous === null || reconsentReasons.length > 0; |
| 479 | if (previous === null) { |
| 480 | reconsentReasons.unshift("First version: the full contract requires consent at install."); |
| 481 | } |
| 482 |
| 483 | return { |
| 484 | permissionsAdded: permissionDiff.added, |
| 485 | permissionsRemoved: permissionDiff.removed, |
| 486 | networkHostsAdded: hostDiff.added, |
| 487 | networkHostsRemoved: hostDiff.removed, |
| 488 | toolEffectsChanged, |
| 489 | schedulesChanged, |
| 490 | surfacesChanged, |
| 491 | webhookEventsAdded: webhookDiff.added, |
| 492 | webhookEventsRemoved: webhookDiff.removed, |
| 493 | hostingChanged, |
| 494 | endpointsAdded: endpointDiff.added, |
| 495 | endpointsRemoved: endpointDiff.removed, |
| 496 | connectionsAdded: connectionDiff.added, |
| 497 | connectionsRemoved: connectionDiff.removed, |
| 498 | siteToolsAdded: siteToolDiff.added, |
| 499 | siteAccessOpened: accessDiff.added, |
| 500 | jobsEscalated, |
| 501 | requiresReconsent, |
| 502 | reconsentReasons, |
| 503 | riskFlags: [...riskFlags].sort(), |
| 504 | }; |
| 505 | } |
| 506 |