335 lines · 12 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 |
| 59 | export interface AppSecurityContractDelta { |
| 60 | permissionsAdded: string[]; |
| 61 | permissionsRemoved: string[]; |
| 62 | networkHostsAdded: string[]; |
| 63 | networkHostsRemoved: string[]; |
| 64 | toolEffectsChanged: ToolEffectChange[]; |
| 65 | schedulesChanged: ScheduleChange[]; |
| 66 | surfacesChanged: SurfaceTierChange[]; |
| 67 | webhookEventsAdded: string[]; |
| 68 | webhookEventsRemoved: string[]; |
| 69 | hostingChanged: HostingChange | null; |
| 70 | /** The one boolean auto-update and re-consent key on. */ |
| 71 | requiresReconsent: boolean; |
| 72 | /** Human-readable reasons behind `requiresReconsent`, for UI. */ |
| 73 | reconsentReasons: string[]; |
| 74 | riskFlags: SecurityRiskFlag[]; |
| 75 | } |
| 76 |
| 77 | const EFFECT_RANK: Record<ToolEffect, number> = { |
| 78 | read: 0, |
| 79 | write: 1, |
| 80 | destructive: 2, |
| 81 | // `external` is a distinct authority class (leaves the workspace); |
| 82 | // ranked above destructive for escalation purposes. |
| 83 | external: 3, |
| 84 | }; |
| 85 |
| 86 | const TIER_RANK: Record<SurfaceTier, number> = { |
| 87 | tree: 0, |
| 88 | react: 1, |
| 89 | web: 2, |
| 90 | }; |
| 91 |
| 92 | function diffStringSets( |
| 93 | previous: readonly string[], |
| 94 | next: readonly string[], |
| 95 | ): { added: string[]; removed: string[] } { |
| 96 | const previousSet = new Set(previous); |
| 97 | const nextSet = new Set(next); |
| 98 | return { |
| 99 | added: [...nextSet].filter((value) => !previousSet.has(value)).sort(), |
| 100 | removed: [...previousSet].filter((value) => !nextSet.has(value)).sort(), |
| 101 | }; |
| 102 | } |
| 103 |
| 104 | function collectSurfaces(manifest: ColineAppManifestV2): Map<string, SurfaceTier> { |
| 105 | const surfaces = new Map<string, SurfaceTier>(); |
| 106 | if (manifest.surfaces.home) { |
| 107 | surfaces.set("home", manifest.surfaces.home.tier); |
| 108 | } |
| 109 | for (const file of manifest.files) { |
| 110 | for (const [name, surface] of Object.entries(file.surfaces)) { |
| 111 | if (surface && typeof surface === "object" && "tier" in surface) { |
| 112 | surfaces.set(`files.${file.typeKey}.${name}`, surface.tier as SurfaceTier); |
| 113 | } |
| 114 | } |
| 115 | } |
| 116 | return surfaces; |
| 117 | } |
| 118 |
| 119 | function collectToolEffects(manifest: ColineAppManifestV2): Map<string, ToolEffect> { |
| 120 | return new Map(manifest.tools.map((tool) => [tool.name, tool.effect])); |
| 121 | } |
| 122 |
| 123 | function externalOverrideKeys(manifest: ColineAppManifestV2): Set<string> { |
| 124 | return new Set( |
| 125 | Object.entries(manifest.hosting.overrides) |
| 126 | .filter(([, model]) => model === "external") |
| 127 | .map(([key]) => key), |
| 128 | ); |
| 129 | } |
| 130 |
| 131 | /** |
| 132 | * Compare two v2 manifests. Pass `previous: null` for a first version — |
| 133 | * everything counts as added and re-consent is trivially required (the |
| 134 | * install consent dialog covers it). |
| 135 | */ |
| 136 | export function compareAppSecurityContract( |
| 137 | previous: ColineAppManifestV2 | null, |
| 138 | next: ColineAppManifestV2, |
| 139 | ): AppSecurityContractDelta { |
| 140 | const reconsentReasons: string[] = []; |
| 141 | const riskFlags = new Set<SecurityRiskFlag>(); |
| 142 |
| 143 | const previousPermissions = previous?.permissions ?? []; |
| 144 | const permissionDiff = diffStringSets(previousPermissions, next.permissions); |
| 145 | if (permissionDiff.added.length > 0) { |
| 146 | reconsentReasons.push( |
| 147 | `Requests ${permissionDiff.added.length} new permission${permissionDiff.added.length === 1 ? "" : "s"}: ${permissionDiff.added.join(", ")}.`, |
| 148 | ); |
| 149 | if (permissionDiff.added.length >= 3) { |
| 150 | riskFlags.add("broad_permission_growth"); |
| 151 | } |
| 152 | } |
| 153 |
| 154 | const previousHosts = previous?.network.allowedHosts ?? []; |
| 155 | const hostDiff = diffStringSets(previousHosts, next.network.allowedHosts); |
| 156 | if (hostDiff.added.length > 0) { |
| 157 | reconsentReasons.push( |
| 158 | `Can now reach ${hostDiff.added.length} new network host${hostDiff.added.length === 1 ? "" : "s"}: ${hostDiff.added.join(", ")}.`, |
| 159 | ); |
| 160 | } |
| 161 | if (next.network.allowedHosts.some((host) => host.startsWith("*."))) { |
| 162 | riskFlags.add("network_host_wildcard"); |
| 163 | } |
| 164 |
| 165 | // Tool effects: record every change; escalate on same-name rank increase |
| 166 | // or a new tool exceeding the app's previous maximum effect. |
| 167 | const previousTools = previous ? collectToolEffects(previous) : new Map<string, ToolEffect>(); |
| 168 | const nextTools = collectToolEffects(next); |
| 169 | const toolEffectsChanged: ToolEffectChange[] = []; |
| 170 | const previousMaxRank = Math.max( |
| 171 | -1, |
| 172 | ...[...previousTools.values()].map((effect) => EFFECT_RANK[effect]), |
| 173 | ); |
| 174 |
| 175 | for (const [name, nextEffect] of nextTools) { |
| 176 | const previousEffect = previousTools.get(name) ?? null; |
| 177 | if (previousEffect === nextEffect) { |
| 178 | continue; |
| 179 | } |
| 180 | toolEffectsChanged.push({ name, previousEffect, nextEffect }); |
| 181 | if (previousEffect !== null && EFFECT_RANK[nextEffect] > EFFECT_RANK[previousEffect]) { |
| 182 | reconsentReasons.push( |
| 183 | `Tool "${name}" escalates from ${previousEffect} to ${nextEffect}.`, |
| 184 | ); |
| 185 | } |
| 186 | if (previousEffect === null && previous !== null && EFFECT_RANK[nextEffect] > previousMaxRank) { |
| 187 | reconsentReasons.push( |
| 188 | `New tool "${name}" (${nextEffect}) exceeds anything the app could previously do.`, |
| 189 | ); |
| 190 | } |
| 191 | } |
| 192 | for (const [name, previousEffect] of previousTools) { |
| 193 | if (!nextTools.has(name)) { |
| 194 | toolEffectsChanged.push({ name, previousEffect, nextEffect: null }); |
| 195 | } |
| 196 | } |
| 197 |
| 198 | const previousDestructive = [...previousTools.values()].filter( |
| 199 | (effect) => effect === "destructive", |
| 200 | ).length; |
| 201 | const nextDestructive = [...nextTools.values()].filter( |
| 202 | (effect) => effect === "destructive", |
| 203 | ).length; |
| 204 | if (nextDestructive > 0 && previousDestructive === 0 && previous !== null) { |
| 205 | riskFlags.add("gains_destructive_tools"); |
| 206 | } |
| 207 | if (nextDestructive > 5) { |
| 208 | riskFlags.add("many_destructive_tools"); |
| 209 | } |
| 210 |
| 211 | // Schedules: informational (they run app code as the app principal). |
| 212 | const previousSchedules = new Map( |
| 213 | (previous?.triggers.schedules ?? []).map((schedule) => [schedule.id, schedule.cron]), |
| 214 | ); |
| 215 | const nextSchedules = new Map( |
| 216 | next.triggers.schedules.map((schedule) => [schedule.id, schedule.cron]), |
| 217 | ); |
| 218 | const schedulesChanged: ScheduleChange[] = []; |
| 219 | for (const [id, cron] of nextSchedules) { |
| 220 | const previousCron = previousSchedules.get(id) ?? null; |
| 221 | if (previousCron !== cron) { |
| 222 | schedulesChanged.push({ id, previousCron, nextCron: cron }); |
| 223 | } |
| 224 | } |
| 225 | for (const [id, cron] of previousSchedules) { |
| 226 | if (!nextSchedules.has(id)) { |
| 227 | schedulesChanged.push({ id, previousCron: cron, nextCron: null }); |
| 228 | } |
| 229 | } |
| 230 |
| 231 | // Surfaces: web tier = developer-origin embed = consent-relevant. |
| 232 | const previousSurfaces = previous ? collectSurfaces(previous) : new Map<string, SurfaceTier>(); |
| 233 | const nextSurfaces = collectSurfaces(next); |
| 234 | const surfacesChanged: SurfaceTierChange[] = []; |
| 235 | for (const [surface, nextTier] of nextSurfaces) { |
| 236 | const previousTier = previousSurfaces.get(surface) ?? null; |
| 237 | if (previousTier === nextTier) { |
| 238 | continue; |
| 239 | } |
| 240 | surfacesChanged.push({ surface, previousTier, nextTier }); |
| 241 | const reachesWeb = |
| 242 | nextTier === "web" && (previousTier === null || TIER_RANK[previousTier] < TIER_RANK.web); |
| 243 | if (reachesWeb && previous !== null) { |
| 244 | reconsentReasons.push( |
| 245 | `Surface "${surface}" now embeds pages from the developer's own website.`, |
| 246 | ); |
| 247 | riskFlags.add("gains_web_surface"); |
| 248 | } |
| 249 | } |
| 250 | for (const [surface, previousTier] of previousSurfaces) { |
| 251 | if (!nextSurfaces.has(surface)) { |
| 252 | surfacesChanged.push({ surface, previousTier, nextTier: null }); |
| 253 | } |
| 254 | } |
| 255 |
| 256 | // Webhooks: outbound workspace data to the developer's backend. |
| 257 | const webhookDiff = diffStringSets( |
| 258 | (previous?.triggers.webhooks ?? []).map((webhook) => webhook.event), |
| 259 | next.triggers.webhooks.map((webhook) => webhook.event), |
| 260 | ); |
| 261 | if (webhookDiff.added.length > 0 && previous !== null) { |
| 262 | reconsentReasons.push( |
| 263 | `Subscribes to ${webhookDiff.added.length} new outbound event${webhookDiff.added.length === 1 ? "" : "s"}: ${webhookDiff.added.join(", ")}.`, |
| 264 | ); |
| 265 | } |
| 266 |
| 267 | // Hosting: where the app's code runs and where workspace data flows. |
| 268 | const previousDefault = previous?.hosting.default ?? "coline"; |
| 269 | const nextDefault = next.hosting.default; |
| 270 | const previousExternalKeys = previous ? externalOverrideKeys(previous) : new Set<string>(); |
| 271 | const nextExternalKeys = externalOverrideKeys(next); |
| 272 | const overridesNowExternal = [...nextExternalKeys] |
| 273 | .filter((key) => !previousExternalKeys.has(key)) |
| 274 | .sort(); |
| 275 | const previousBaseUrl = previous?.hosting.external?.baseUrl ?? null; |
| 276 | const nextBaseUrl = next.hosting.external?.baseUrl ?? null; |
| 277 | const externalBaseUrlChanged = |
| 278 | previousBaseUrl !== null && nextBaseUrl !== null && previousBaseUrl !== nextBaseUrl; |
| 279 |
| 280 | let hostingChanged: HostingChange | null = null; |
| 281 | if ( |
| 282 | previousDefault !== nextDefault || |
| 283 | overridesNowExternal.length > 0 || |
| 284 | previousBaseUrl !== nextBaseUrl |
| 285 | ) { |
| 286 | hostingChanged = { |
| 287 | previousDefault, |
| 288 | nextDefault, |
| 289 | overridesNowExternal, |
| 290 | previousExternalBaseUrl: previousBaseUrl, |
| 291 | nextExternalBaseUrl: nextBaseUrl, |
| 292 | externalBaseUrlChanged, |
| 293 | }; |
| 294 | } |
| 295 | if (previous !== null) { |
| 296 | const gainsExternal = |
| 297 | (previousDefault === "coline" && nextDefault === "external") || |
| 298 | overridesNowExternal.length > 0 || |
| 299 | (previousBaseUrl === null && nextBaseUrl !== null); |
| 300 | if (gainsExternal) { |
| 301 | reconsentReasons.push( |
| 302 | "Parts of the app now run on the developer's own infrastructure.", |
| 303 | ); |
| 304 | riskFlags.add("gains_external_hosting"); |
| 305 | } |
| 306 | if (externalBaseUrlChanged) { |
| 307 | reconsentReasons.push( |
| 308 | `The app's external backend moved from ${previousBaseUrl} to ${nextBaseUrl}.`, |
| 309 | ); |
| 310 | riskFlags.add("external_base_url_changed"); |
| 311 | } |
| 312 | } |
| 313 |
| 314 | const requiresReconsent = previous === null || reconsentReasons.length > 0; |
| 315 | if (previous === null) { |
| 316 | reconsentReasons.unshift("First version: the full contract requires consent at install."); |
| 317 | } |
| 318 |
| 319 | return { |
| 320 | permissionsAdded: permissionDiff.added, |
| 321 | permissionsRemoved: permissionDiff.removed, |
| 322 | networkHostsAdded: hostDiff.added, |
| 323 | networkHostsRemoved: hostDiff.removed, |
| 324 | toolEffectsChanged, |
| 325 | schedulesChanged, |
| 326 | surfacesChanged, |
| 327 | webhookEventsAdded: webhookDiff.added, |
| 328 | webhookEventsRemoved: webhookDiff.removed, |
| 329 | hostingChanged, |
| 330 | requiresReconsent, |
| 331 | reconsentReasons, |
| 332 | riskFlags: [...riskFlags].sort(), |
| 333 | }; |
| 334 | } |
| 335 |