improvement(files): centralize operations across APIs and Copilot

[TheodoreSpeaks]

Summary

• introduce a reusable, principal-aware application-operation foundation for canonical loading, workspace authorization, business execution, semantic audit, and post-success domain effects
• migrate internal and v2 workspace-file operations to declarative route adapters while preserving their independent authentication, contracts, error envelopes, presenters, rate policies, and analytics
• route Copilot file tools through shared application use cases using delegated principals derived only from trusted execution context
• harden upload control legs with principal binding and current authorization while preserving workspace-key uploads and billing-owner attribution where legacy storage fields require it
• share workspace filename validation across internal and v2 contracts and add a resource-agnostic migration skill for applying the architecture to other domains

Architecture

surface admission
-> authenticate trusted credential/context
-> construct Principal
-> operation rate policy
-> parse surface contract
-> authorized application use case
-> load canonical resource context
-> conceal asserted-scope mismatches
-> authorize the semantic operation
-> execute manager/repository behavior
-> project semantic audit
-> run shared post-success effects
-> surface-specific presenter

• ApplicationOperation and WorkspaceOperation define one stable semantic operation, required role, accepted principal kinds, and workspace-key policy.
• defineAuthorizedWorkspaceUseCase owns the shared authorization/execution/audit lifecycle; file-specific bindings only provide resource delegation policy.
• Managers and repositories receive canonical identifiers and workspace scope, never credentials or principals.
• Internal routes authenticate sessions with defineInternalJsonRoute; v2 routes authenticate API keys with the v2 JSON/binary adapters.
• Copilot adapters normalize trusted tool context into delegated principals and call the same application use cases. Model-provided workspace, identity, operation, and permission fields are never authoritative.
• Semantic audit is shared application behavior. Surface analytics such as captureServerEvent remain surface-specific.

Migrated scope

• internal workspace-file JSON and binary routes
• v2 workspace-file metadata, content, create, update, delete, restore, move, folders, sharing, downloads, and uploads
• file bulk operations with bounded inputs and authoritative affected-resource reporting
• workspace-file upload create, parts, completion, and cancellation control paths
• Copilot file tools, resumable aliases, VFS reference resolution, and generated-output writes
• shared principal, authorization, typed error, route-definition, presenter, rate-policy, and contract primitives

Compatibility and non-goals

• v1 routes and v1 middleware are unchanged
• no database migration is introduced
• internal and v2 wire contracts remain independently defined where their request or response shapes differ; shared primitives carry common validation invariants
• workspace API keys may perform explicitly allowed read/write operations, including uploads, but cannot exceed the write ceiling
• billing-owner identity is used only for billing or required legacy attribution fields, never for authorization, rate-limit identity, delegated identity, or human audit attribution
• existing in-flight upload sessions retain an explicit compatibility path; newly created sessions use server-authored principal binding
• large-body, binary, streaming, bulk, and upload operations retain lifecycle-specific admission rather than being forced through one JSON pipeline

Migration tooling

• replace the file-only guide with migrate-application-operation
• cover internal APIs, public/versioned APIs, Copilot, and other trusted tool runtimes
• require every protected read, mutation, canonical lookup, and authorization-sensitive reference resolution to enter through an application use case
• permit surface helpers only for trusted principal normalization, argument translation, code-defined operation selection, application invocation, and presentation

Validation

• focused Vitest coverage across principals, authorization, application use cases, internal/v2 route adapters, file operations, upload lifecycle behavior, contracts, and Copilot tools
• bunx turbo run type-check --filter=sim --filter=@sim/auth
• bun run lint
• bun run check:api-validation:strict
• bun run check:openapi
• bun run skills:check
• git diff --check

Type of Change

• Improvement

Checklist

• Code follows project style guidelines
• Self-reviewed changes
• Tests added or updated and passing
• No new warnings introduced
• v1 behavior remains out of scope
• No database migration introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 8, 2026 9:11am

[cursor]

PR Summary

High Risk
Changes touch authorization, upload finalization, and multiple API/tool entry points for protected file data; regressions could affect access control or idempotent upload completion across surfaces.

Overview
This PR moves workspace file behavior (reads, writes, uploads, renames, deletes, downloads, and internal tool paths) behind shared application use cases with explicit Principal identity, instead of route-local permission checks and direct manager calls.

Internal upload routes now call upload-session application helpers that bind sessions to the authenticated principal, re-authorize workspace-file control legs, and finalize through finalizeUploadPurpose with principal-aware audit and workspace-key billing attribution only for legacy columns.

V2 file routes (metadata, content, download/rename/delete) are wired through defineV2JsonRoute / defineV2BinaryRoute, semantic fileOperations, operation rate limits, and concealed authorization (forbidden → not found).

Executor and internal file-manage tools construct delegated principals and call the same use cases (create, read, update, resolve references); query userId is no longer used as the auth identity.

Also adds a migrate-application-operation agent skill/command and extends the ship audit list with check:openapi and check:sql-date-binding. V1 routes and schema are unchanged per the PR scope.

^{Reviewed by Cursor Bugbot for commit 0ab6d68. Bugbot is set up for automated code reviews on this repo. Configure here.}

[TheodoreSpeaks]

@greptile-apps

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit b061854. Configure here.}

[greptile-apps]

Greptile Summary

The PR centralizes workspace-file operations behind principal-aware application services while preserving surface-specific authentication, contracts, and presentation.

• Adds shared operation definitions, authorization wrappers, typed principals, rate policies, and transactional file use cases.
• Migrates internal, v2, upload, and Copilot adapters to the shared application boundary.
• Adds focused authorization, route, upload-lifecycle, and file-operation tests.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/core/application/authorized-workspace-use-case.ts	Introduces the common lifecycle for principal validation, canonical context loading, authorization, execution, audit projection, and post-success effects.
apps/sim/lib/core/application/workspace-authorization.ts	Centralizes session, personal-key, workspace-key, and delegated-principal authorization with canonical workspace and delegation-scope checks.
apps/sim/lib/workspace-files/application/rename-workspace-file.ts	Routes file rename behavior through the shared authorized application boundary and authoritative manager operation.
apps/sim/lib/uploads/upload-session/application.ts	Adds application-level authorization and immutable identity binding around multipart upload control operations.
apps/sim/lib/copilot/auth/file-delegation.ts	Constructs short-lived delegated file principals from trusted Copilot execution context.
apps/sim/lib/copilot/application/execute-file-use-case.ts	Adapts Copilot file tools to shared application use cases and authorized reference resolution.
apps/sim/lib/api/server/routes/v2-json-route.ts	Adds a declarative v2 JSON route adapter that keeps API-key authentication, rate policy, parsing, and response projection outside application logic.
packages/auth/src/principal.ts	Defines explicit principal variants and structured audit attribution shared by application operations.

Sequence Diagram

sequenceDiagram
participant Surface as Internal / v2 / Copilot adapter
participant Auth as Authentication adapter
participant App as Authorized file use case
participant Context as Canonical context loader
participant Authz as Workspace authorization
participant Manager as File manager / repository
Surface->>Auth: Validate surface credential or trusted context
Auth-->>Surface: Principal
Surface->>App: Principal + operation input
App->>Context: Load canonical file/workspace context
Context-->>App: Canonical identifiers and policy state
App->>Authz: Authorize principal for semantic operation
Authz-->>App: Allowed
App->>Manager: Execute scoped transaction
Manager-->>App: Authoritative result
App-->>Surface: Typed result
Surface-->>Surface: Render surface-specific response

Loading

_{Reviews (5): Last reviewed commit: "docs(skills): generalize application ope..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile-apps

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 58d8d19. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 72ae9f5. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 3700dff. Configure here.}

[TheodoreSpeaks]

@greptile