460 lines · 17 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_public_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 | publicToolsAdded: string[]; |
| 77 | jobsEscalated: string[]; |
| 78 | /** The one boolean auto-update and re-consent key on. */ |
| 79 | requiresReconsent: boolean; |
| 80 | /** Human-readable reasons behind `requiresReconsent`, for UI. */ |
| 81 | reconsentReasons: string[]; |
| 82 | riskFlags: SecurityRiskFlag[]; |
| 83 | } |
| 84 |
| 85 | const EFFECT_RANK: Record<ToolEffect, number> = { |
| 86 | read: 0, |
| 87 | write: 1, |
| 88 | destructive: 2, |
| 89 | // `external` is a distinct authority class (leaves the workspace); |
| 90 | // ranked above destructive for escalation purposes. |
| 91 | external: 3, |
| 92 | }; |
| 93 |
| 94 | const TIER_RANK: Record<SurfaceTier, number> = { |
| 95 | tree: 0, |
| 96 | react: 1, |
| 97 | web: 2, |
| 98 | }; |
| 99 |
| 100 | function diffStringSets( |
| 101 | previous: readonly string[], |
| 102 | next: readonly string[], |
| 103 | ): { added: string[]; removed: string[] } { |
| 104 | const previousSet = new Set(previous); |
| 105 | const nextSet = new Set(next); |
| 106 | return { |
| 107 | added: [...nextSet].filter((value) => !previousSet.has(value)).sort(), |
| 108 | removed: [...previousSet].filter((value) => !nextSet.has(value)).sort(), |
| 109 | }; |
| 110 | } |
| 111 |
| 112 | function collectSurfaces(manifest: ColineAppManifestV2): Map<string, SurfaceTier> { |
| 113 | const surfaces = new Map<string, SurfaceTier>(); |
| 114 | if (manifest.surfaces.home) { |
| 115 | surfaces.set("home", manifest.surfaces.home.tier); |
| 116 | } |
| 117 | if (manifest.surfaces.public) { |
| 118 | surfaces.set("public", manifest.surfaces.public.tier); |
| 119 | } |
| 120 | for (const file of manifest.files) { |
| 121 | for (const [name, surface] of Object.entries(file.surfaces)) { |
| 122 | if (surface && typeof surface === "object" && "tier" in surface) { |
| 123 | surfaces.set(`files.${file.typeKey}.${name}`, surface.tier as SurfaceTier); |
| 124 | } |
| 125 | } |
| 126 | } |
| 127 | return surfaces; |
| 128 | } |
| 129 |
| 130 | function collectToolEffects(manifest: ColineAppManifestV2): Map<string, ToolEffect> { |
| 131 | return new Map(manifest.tools.map((tool) => [tool.name, tool.effect])); |
| 132 | } |
| 133 |
| 134 | function externalOverrideKeys(manifest: ColineAppManifestV2): Set<string> { |
| 135 | return new Set( |
| 136 | Object.entries(manifest.hosting.overrides) |
| 137 | .filter(([, model]) => model === "external") |
| 138 | .map(([key]) => key), |
| 139 | ); |
| 140 | } |
| 141 |
| 142 | /** |
| 143 | * Compare two v2 manifests. Pass `previous: null` for a first version — |
| 144 | * everything counts as added and re-consent is trivially required (the |
| 145 | * install consent dialog covers it). |
| 146 | */ |
| 147 | export function compareAppSecurityContract( |
| 148 | previous: ColineAppManifestV2 | null, |
| 149 | next: ColineAppManifestV2, |
| 150 | ): AppSecurityContractDelta { |
| 151 | const reconsentReasons: string[] = []; |
| 152 | const riskFlags = new Set<SecurityRiskFlag>(); |
| 153 |
| 154 | const previousPermissions = previous?.permissions ?? []; |
| 155 | const permissionDiff = diffStringSets(previousPermissions, next.permissions); |
| 156 | if (permissionDiff.added.length > 0) { |
| 157 | reconsentReasons.push( |
| 158 | `Requests ${permissionDiff.added.length} new permission${permissionDiff.added.length === 1 ? "" : "s"}: ${permissionDiff.added.join(", ")}.`, |
| 159 | ); |
| 160 | if (permissionDiff.added.length >= 3) { |
| 161 | riskFlags.add("broad_permission_growth"); |
| 162 | } |
| 163 | } |
| 164 |
| 165 | const previousHosts = previous?.network.allowedHosts ?? []; |
| 166 | const hostDiff = diffStringSets(previousHosts, next.network.allowedHosts); |
| 167 | if (hostDiff.added.length > 0) { |
| 168 | reconsentReasons.push( |
| 169 | `Can now reach ${hostDiff.added.length} new network host${hostDiff.added.length === 1 ? "" : "s"}: ${hostDiff.added.join(", ")}.`, |
| 170 | ); |
| 171 | } |
| 172 | if (next.network.allowedHosts.some((host) => host.startsWith("*."))) { |
| 173 | riskFlags.add("network_host_wildcard"); |
| 174 | } |
| 175 |
| 176 | // Tool effects: record every change; escalate on same-name rank increase |
| 177 | // or a new tool exceeding the app's previous maximum effect. |
| 178 | const previousTools = previous ? collectToolEffects(previous) : new Map<string, ToolEffect>(); |
| 179 | const nextTools = collectToolEffects(next); |
| 180 | const toolEffectsChanged: ToolEffectChange[] = []; |
| 181 | const previousMaxRank = Math.max( |
| 182 | -1, |
| 183 | ...[...previousTools.values()].map((effect) => EFFECT_RANK[effect]), |
| 184 | ); |
| 185 |
| 186 | for (const [name, nextEffect] of nextTools) { |
| 187 | const previousEffect = previousTools.get(name) ?? null; |
| 188 | if (previousEffect === nextEffect) { |
| 189 | continue; |
| 190 | } |
| 191 | toolEffectsChanged.push({ name, previousEffect, nextEffect }); |
| 192 | if (previousEffect !== null && EFFECT_RANK[nextEffect] > EFFECT_RANK[previousEffect]) { |
| 193 | reconsentReasons.push( |
| 194 | `Tool "${name}" escalates from ${previousEffect} to ${nextEffect}.`, |
| 195 | ); |
| 196 | } |
| 197 | if (previousEffect === null && previous !== null && EFFECT_RANK[nextEffect] > previousMaxRank) { |
| 198 | reconsentReasons.push( |
| 199 | `New tool "${name}" (${nextEffect}) exceeds anything the app could previously do.`, |
| 200 | ); |
| 201 | } |
| 202 | } |
| 203 | for (const [name, previousEffect] of previousTools) { |
| 204 | if (!nextTools.has(name)) { |
| 205 | toolEffectsChanged.push({ name, previousEffect, nextEffect: null }); |
| 206 | } |
| 207 | } |
| 208 |
| 209 | const previousDestructive = [...previousTools.values()].filter( |
| 210 | (effect) => effect === "destructive", |
| 211 | ).length; |
| 212 | const nextDestructive = [...nextTools.values()].filter( |
| 213 | (effect) => effect === "destructive", |
| 214 | ).length; |
| 215 | if (nextDestructive > 0 && previousDestructive === 0 && previous !== null) { |
| 216 | riskFlags.add("gains_destructive_tools"); |
| 217 | } |
| 218 | if (nextDestructive > 5) { |
| 219 | riskFlags.add("many_destructive_tools"); |
| 220 | } |
| 221 |
| 222 | // Schedules: informational (they run app code as the app principal). |
| 223 | const previousSchedules = new Map( |
| 224 | (previous?.triggers.schedules ?? []).map((schedule) => [schedule.id, schedule.cron]), |
| 225 | ); |
| 226 | const nextSchedules = new Map( |
| 227 | next.triggers.schedules.map((schedule) => [schedule.id, schedule.cron]), |
| 228 | ); |
| 229 | const schedulesChanged: ScheduleChange[] = []; |
| 230 | for (const [id, cron] of nextSchedules) { |
| 231 | const previousCron = previousSchedules.get(id) ?? null; |
| 232 | if (previousCron !== cron) { |
| 233 | schedulesChanged.push({ id, previousCron, nextCron: cron }); |
| 234 | } |
| 235 | } |
| 236 | for (const [id, cron] of previousSchedules) { |
| 237 | if (!nextSchedules.has(id)) { |
| 238 | schedulesChanged.push({ id, previousCron: cron, nextCron: null }); |
| 239 | } |
| 240 | } |
| 241 |
| 242 | // Surfaces: web tier = developer-origin embed = consent-relevant. |
| 243 | const previousSurfaces = previous ? collectSurfaces(previous) : new Map<string, SurfaceTier>(); |
| 244 | const nextSurfaces = collectSurfaces(next); |
| 245 | const surfacesChanged: SurfaceTierChange[] = []; |
| 246 | for (const [surface, nextTier] of nextSurfaces) { |
| 247 | const previousTier = previousSurfaces.get(surface) ?? null; |
| 248 | if (previousTier === nextTier) { |
| 249 | continue; |
| 250 | } |
| 251 | surfacesChanged.push({ surface, previousTier, nextTier }); |
| 252 | const reachesWeb = |
| 253 | nextTier === "web" && (previousTier === null || TIER_RANK[previousTier] < TIER_RANK.web); |
| 254 | if (reachesWeb && previous !== null) { |
| 255 | reconsentReasons.push( |
| 256 | `Surface "${surface}" now embeds pages from the developer's own website.`, |
| 257 | ); |
| 258 | riskFlags.add("gains_web_surface"); |
| 259 | } |
| 260 | } |
| 261 | for (const [surface, previousTier] of previousSurfaces) { |
| 262 | if (!nextSurfaces.has(surface)) { |
| 263 | surfacesChanged.push({ surface, previousTier, nextTier: null }); |
| 264 | } |
| 265 | } |
| 266 |
| 267 | // Webhooks: outbound workspace data to the developer's backend. |
| 268 | const webhookDiff = diffStringSets( |
| 269 | (previous?.triggers.webhooks ?? []).map((webhook) => webhook.event), |
| 270 | next.triggers.webhooks.map((webhook) => webhook.event), |
| 271 | ); |
| 272 | if (webhookDiff.added.length > 0 && previous !== null) { |
| 273 | reconsentReasons.push( |
| 274 | `Subscribes to ${webhookDiff.added.length} new outbound event${webhookDiff.added.length === 1 ? "" : "s"}: ${webhookDiff.added.join(", ")}.`, |
| 275 | ); |
| 276 | } |
| 277 |
| 278 | // Hosting: where the app's code runs and where workspace data flows. |
| 279 | const previousDefault = previous?.hosting.default ?? "coline"; |
| 280 | const nextDefault = next.hosting.default; |
| 281 | const previousExternalKeys = previous ? externalOverrideKeys(previous) : new Set<string>(); |
| 282 | const nextExternalKeys = externalOverrideKeys(next); |
| 283 | const overridesNowExternal = [...nextExternalKeys] |
| 284 | .filter((key) => !previousExternalKeys.has(key)) |
| 285 | .sort(); |
| 286 | const previousBaseUrl = previous?.hosting.external?.baseUrl ?? null; |
| 287 | const nextBaseUrl = next.hosting.external?.baseUrl ?? null; |
| 288 | const externalBaseUrlChanged = |
| 289 | previousBaseUrl !== null && nextBaseUrl !== null && previousBaseUrl !== nextBaseUrl; |
| 290 |
| 291 | let hostingChanged: HostingChange | null = null; |
| 292 | if ( |
| 293 | previousDefault !== nextDefault || |
| 294 | overridesNowExternal.length > 0 || |
| 295 | previousBaseUrl !== nextBaseUrl |
| 296 | ) { |
| 297 | hostingChanged = { |
| 298 | previousDefault, |
| 299 | nextDefault, |
| 300 | overridesNowExternal, |
| 301 | previousExternalBaseUrl: previousBaseUrl, |
| 302 | nextExternalBaseUrl: nextBaseUrl, |
| 303 | externalBaseUrlChanged, |
| 304 | }; |
| 305 | } |
| 306 | if (previous !== null) { |
| 307 | const gainsExternal = |
| 308 | (previousDefault === "coline" && nextDefault === "external") || |
| 309 | overridesNowExternal.length > 0 || |
| 310 | (previousBaseUrl === null && nextBaseUrl !== null); |
| 311 | if (gainsExternal) { |
| 312 | reconsentReasons.push( |
| 313 | "Parts of the app now run on the developer's own infrastructure.", |
| 314 | ); |
| 315 | riskFlags.add("gains_external_hosting"); |
| 316 | } |
| 317 | if (externalBaseUrlChanged) { |
| 318 | reconsentReasons.push( |
| 319 | `The app's external backend moved from ${previousBaseUrl} to ${nextBaseUrl}.`, |
| 320 | ); |
| 321 | riskFlags.add("external_base_url_changed"); |
| 322 | } |
| 323 | } |
| 324 |
| 325 | // Endpoints: new inbound doors into the app. |
| 326 | const endpointDiff = diffStringSets( |
| 327 | (previous?.endpoints ?? []).map((endpoint) => endpoint.id), |
| 328 | next.endpoints.map((endpoint) => endpoint.id), |
| 329 | ); |
| 330 | if (endpointDiff.added.length > 0 && previous !== null) { |
| 331 | reconsentReasons.push( |
| 332 | `Receives requests at ${endpointDiff.added.length} new endpoint${endpointDiff.added.length === 1 ? "" : "s"}: ${endpointDiff.added.join(", ")}.`, |
| 333 | ); |
| 334 | } |
| 335 | // An existing endpoint that drops its signature check, or accepts more |
| 336 | // methods, is a wider door than the one that was approved. |
| 337 | const previousEndpoints = new Map((previous?.endpoints ?? []).map((endpoint) => [endpoint.id, endpoint])); |
| 338 | for (const endpoint of next.endpoints) { |
| 339 | const before = previousEndpoints.get(endpoint.id); |
| 340 | if (!before || previous === null) continue; |
| 341 | if (endpoint.verify.kind === "none" && before.verify.kind !== "none") { |
| 342 | reconsentReasons.push(`Endpoint "${endpoint.id}" no longer verifies who is calling it.`); |
| 343 | } |
| 344 | const methodDiff = diffStringSets(before.methods, endpoint.methods); |
| 345 | if (methodDiff.added.length > 0) { |
| 346 | reconsentReasons.push(`Endpoint "${endpoint.id}" now accepts ${methodDiff.added.join(", ")} requests.`); |
| 347 | } |
| 348 | } |
| 349 | if (next.endpoints.some((endpoint) => endpoint.verify.kind === "none")) { |
| 350 | riskFlags.add("unverified_endpoint"); |
| 351 | } |
| 352 |
| 353 | // Connections: accounts on other services, used on members' behalf. |
| 354 | const previousConnections = new Map( |
| 355 | (previous?.connections ?? []).map((connection) => [connection.key, connection]), |
| 356 | ); |
| 357 | const connectionDiff = diffStringSets( |
| 358 | [...previousConnections.keys()], |
| 359 | next.connections.map((connection) => connection.key), |
| 360 | ); |
| 361 | if (connectionDiff.added.length > 0 && previous !== null) { |
| 362 | reconsentReasons.push(`Asks to connect new accounts: ${connectionDiff.added.join(", ")}.`); |
| 363 | } |
| 364 | for (const connection of next.connections) { |
| 365 | const before = previousConnections.get(connection.key); |
| 366 | if (!before || previous === null) continue; |
| 367 | const scopeDiff = diffStringSets(before.oauth2.scopes, connection.oauth2.scopes); |
| 368 | const connectionHostDiff = diffStringSets(before.hosts, connection.hosts); |
| 369 | if (scopeDiff.added.length > 0 || connectionHostDiff.added.length > 0) { |
| 370 | const details = [ |
| 371 | scopeDiff.added.length > 0 ? `scopes: ${scopeDiff.added.join(", ")}` : null, |
| 372 | connectionHostDiff.added.length > 0 ? `hosts: ${connectionHostDiff.added.join(", ")}` : null, |
| 373 | ].filter(Boolean); |
| 374 | reconsentReasons.push( |
| 375 | `Connection "${connection.key}" requests more access (${details.join("; ")}).`, |
| 376 | ); |
| 377 | } |
| 378 | // The token endpoint receives authorization codes (and so, in effect, |
| 379 | // the account's tokens); moving it or the sign-in page is a new trust. |
| 380 | if ( |
| 381 | before.oauth2.tokenUrl !== connection.oauth2.tokenUrl || |
| 382 | before.oauth2.authorizeUrl !== connection.oauth2.authorizeUrl || |
| 383 | before.oauth2.clientId !== connection.oauth2.clientId |
| 384 | ) { |
| 385 | reconsentReasons.push(`Connection "${connection.key}" signs in through a different service or client.`); |
| 386 | } |
| 387 | if (before.scope !== connection.scope) { |
| 388 | reconsentReasons.push( |
| 389 | connection.scope === "workspace" |
| 390 | ? `Connection "${connection.key}" becomes one shared workspace account.` |
| 391 | : `Connection "${connection.key}" becomes a per-member account.`, |
| 392 | ); |
| 393 | } |
| 394 | } |
| 395 |
| 396 | // Public surface: what visitors outside the workspace can trigger. |
| 397 | const publicToolDiff = diffStringSets( |
| 398 | previous?.surfaces.public?.tools ?? [], |
| 399 | next.surfaces.public?.tools ?? [], |
| 400 | ); |
| 401 | if (next.surfaces.public && !previous?.surfaces.public && previous !== null) { |
| 402 | reconsentReasons.push("Adds a public page people outside the workspace can open."); |
| 403 | riskFlags.add("gains_public_surface"); |
| 404 | } else if (publicToolDiff.added.length > 0 && previous !== null) { |
| 405 | reconsentReasons.push( |
| 406 | `Visitors to the public page can now run: ${publicToolDiff.added.join(", ")}.`, |
| 407 | ); |
| 408 | } |
| 409 |
| 410 | // Jobs: background work escalating its effect ceiling, or a new job |
| 411 | // exceeding anything the app (tools or jobs) could previously do. |
| 412 | const previousJobs = new Map((previous?.jobs ?? []).map((job) => [job.name, job.effect])); |
| 413 | const previousAuthorityRank = Math.max( |
| 414 | previousMaxRank, |
| 415 | ...[...previousJobs.values()].map((effect) => EFFECT_RANK[effect]), |
| 416 | ); |
| 417 | const jobsEscalated: string[] = []; |
| 418 | for (const job of next.jobs) { |
| 419 | const before = previousJobs.get(job.name); |
| 420 | if (before && EFFECT_RANK[job.effect] > EFFECT_RANK[before]) { |
| 421 | jobsEscalated.push(job.name); |
| 422 | reconsentReasons.push( |
| 423 | `Background job "${job.name}" escalates from ${before} to ${job.effect}.`, |
| 424 | ); |
| 425 | } else if (!before && previous !== null && EFFECT_RANK[job.effect] > previousAuthorityRank) { |
| 426 | jobsEscalated.push(job.name); |
| 427 | reconsentReasons.push( |
| 428 | `New background job "${job.name}" (${job.effect}) exceeds anything the app could previously do.`, |
| 429 | ); |
| 430 | } |
| 431 | } |
| 432 |
| 433 | const requiresReconsent = previous === null || reconsentReasons.length > 0; |
| 434 | if (previous === null) { |
| 435 | reconsentReasons.unshift("First version: the full contract requires consent at install."); |
| 436 | } |
| 437 |
| 438 | return { |
| 439 | permissionsAdded: permissionDiff.added, |
| 440 | permissionsRemoved: permissionDiff.removed, |
| 441 | networkHostsAdded: hostDiff.added, |
| 442 | networkHostsRemoved: hostDiff.removed, |
| 443 | toolEffectsChanged, |
| 444 | schedulesChanged, |
| 445 | surfacesChanged, |
| 446 | webhookEventsAdded: webhookDiff.added, |
| 447 | webhookEventsRemoved: webhookDiff.removed, |
| 448 | hostingChanged, |
| 449 | endpointsAdded: endpointDiff.added, |
| 450 | endpointsRemoved: endpointDiff.removed, |
| 451 | connectionsAdded: connectionDiff.added, |
| 452 | connectionsRemoved: connectionDiff.removed, |
| 453 | publicToolsAdded: publicToolDiff.added, |
| 454 | jobsEscalated, |
| 455 | requiresReconsent, |
| 456 | reconsentReasons, |
| 457 | riskFlags: [...riskFlags].sort(), |
| 458 | }; |
| 459 | } |
| 460 |