Carlos Florêncio
73 lines
3.0 KiB
Markdown
73 lines
3.0 KiB
Markdown
---
|
|
id: plugins-canvas-workspace-data-scope-design
|
|
title: Canvas placement and data scope in the web-app runtime
|
|
status: draft
|
|
system: plugins
|
|
owners:
|
|
- kandev
|
|
created: 2026-09-23
|
|
last_updated: 2026-09-23
|
|
requirements: []
|
|
---
|
|
|
|
# Canvas placement and data scope in the web-app runtime
|
|
|
|
## Boundary
|
|
|
|
This is the Plugins runtime implementation contract for the
|
|
[Canvas workspace preview requirement](../../canvases/requirements/task-canvas-workspace-preview.md).
|
|
Canvases decides when an owner-authorized local app may use workspace data.
|
|
Plugins persists and enforces that decision; it does not infer authority from
|
|
the manifest or browser request. The existing
|
|
[isolated web-app design](isolated-web-app-contributions.md) remains the general
|
|
runtime contract.
|
|
|
|
## Instance model and grants
|
|
|
|
Add nullable `plugin_instances.data_scope_kind`. A null value resolves to
|
|
`scope_kind` for retained rows and non-canvas instances. A non-null workspace
|
|
data scope is valid only for a `local_canvas` instance placed in a task or
|
|
workspace with a trusted `workspace_id`. Reject any attempt to use an
|
|
installation-wide data scope for a canvas. Creation, reviewed upgrade, and
|
|
promotion update the field and grants through transactions owned by the
|
|
canvas lifecycle service.
|
|
|
|
Grant fit, release activation, and runtime validation compare each declared
|
|
permission with the effective data scope. An exact task grant cannot cover
|
|
workspace data. A workspace grant authorizes only the bound workspace and is
|
|
still intersected with current user and resource access. Revocation and scope
|
|
changes increment the existing grant generation.
|
|
|
|
## Runtime binding and protocol
|
|
|
|
Add effective `DataScopeKind` to `webapp.CapabilityBinding`, sourced from the
|
|
persisted instance and checked against it on every request. Keep `ScopeKind`
|
|
for placement and task lifecycle. The relative context response exposes both
|
|
`scope_kind` and `data_scope_kind`; empty historical data scope resolves to
|
|
placement scope.
|
|
|
|
Task lists, single-task reads, task writes, messages, workflow reads, task
|
|
dependency projections, and events use data scope. Workspace-data task
|
|
canvases use the paginated workspace path, bounded by the trusted workspace
|
|
ID, rather than the task-only shortcut. Explicit foreign `workspace_id`
|
|
filters fail. Non-canvas instances retain current behavior.
|
|
|
|
## Compatibility and failure
|
|
|
|
The schema migration does not widen old rows. Historical runtime bindings
|
|
and grants remain task-scoped until a reviewed update changes them. A stale
|
|
binding, missing workspace/task, revoked grant, or mismatched data scope fails
|
|
closed through existing safe errors. Current plugin manifests and immutable
|
|
canvas packages need no rewrite.
|
|
|
|
## Verification
|
|
|
|
Test SQLite and PostgreSQL mapping, legacy null fallback, invalid scope
|
|
combinations, runtime token invalidation, exact grants, all workspace task
|
|
pages, task read/write and message paths, workflow and event scope, dependency
|
|
redaction, and foreign-workspace denial.
|
|
|
|
## Related decision
|
|
|
|
- [Task canvas workspace data](../../../decisions/2026-09-23-task-canvas-workspace-data.md)
|