feat(apps): integrate governed app platform and native experiences

.env.example

@@ -78,6 +78,33 @@ NEXT_PUBLIC_FEATURE_HUDDLES=false
 # beta. Enable the API and bake the public UI flag into the same build.
 DEFT_APPS_ENABLED=false
 NEXT_PUBLIC_FEATURE_APPS=false
+# Private resource sync remains a separate experimental opt-in. The web flag
+# must be baked into a source build; it does not grant read or sync authority.
+NEXT_PUBLIC_FEATURE_APP_RESOURCE_SYNC=false
+DEFT_APP_RESOURCE_SYNC_CHANNEL_ENABLED=false
+DEFT_APP_RESOURCE_SYNC_SCHEDULER_ENABLED=false
+# Protocol 7 attachment custody also requires owner-reviewed parent and binary consent.
+DEFT_APP_ATTACHMENT_BROKER_ENABLED=false
+# Build-time UI opt-in for reviewed attachment setup and owner viewing; requires
+# the Apps and private resource sync UI flags. This grants no data access.
+NEXT_PUBLIC_FEATURE_APP_ATTACHMENT_BROKER=false
+# Installed App code needs a separate session-bound review before reading saved
+# private fields. Sync consent alone never grants this experimental exposure.
+DEFT_APP_EXPERIENCE_RESOURCE_EXPOSURE_ENABLED=false
+# Protocol-v5 effects retain separate Runtime binding and per-invocation review.
+DEFT_APP_V5_RUNTIME_ACTIONS_ENABLED=false
+# Opt-in protocol 6 native Calendar bindings; each invocation requires owner approval.
+DEFT_APP_NATIVE_CALENDAR_ENABLED=false
+# Explicit human private-resource sharing; recipient rights require owner review.
+DEFT_APP_PRIVATE_SHARING_ENABLED=false
+NEXT_PUBLIC_FEATURE_APP_PRIVATE_SHARING=false
+# Exact personal/employee MCP credential access requires its own owner review.
+DEFT_APP_PRIVATE_MCP_ENABLED=false
+NEXT_PUBLIC_FEATURE_APP_PRIVATE_MCP=false
+# Private Defty context requires a separate owner review of fields and model destination.
+# Retained encrypted history needs its original key versions after revocation.
+DEFT_APP_PRIVATE_DEFTY_ENABLED=false
+NEXT_PUBLIC_FEATURE_APP_PRIVATE_DEFTY=false
 DEFT_APP_DEVELOPER_PAIRING_ENABLED=false
 # The App Run engine can decrypt and drain accepted work only when this exact
 # opt-in and valid purpose-separated keyrings are supplied.

.gitattributes

@@ -1,3 +1,11 @@
 scripts/docker-entrypoint.sh text eol=lf
 docs/examples/operations/*.sh text eol=lf
 **/deft.app.lock.json text eol=lf
+# Migration checksums cover physical bytes; pin new files without rewriting history.
+packages/db/upgrades/0.3.0-preview.51-app-attachment-composition.sql text eol=lf
+packages/db/upgrades/0.3.0-preview.52-private-defty-context.sql text eol=lf
+packages/db/upgrades/0.3.0-preview.54-app-experience-consent.sql text eol=lf
+# Preserve the exact mixed line-ending bytes already applied in preview databases.
+packages/db/upgrades/0.3.0-preview.53-app-private-state.sql -text whitespace=cr-at-eol,-blank-at-eof
+packages/db/upgrades/0.3.0-preview.55-app-action-batches.sql -text whitespace=cr-at-eol,-blank-at-eof
+packages/db/upgrades/0.3.0-preview.56-app-action-batch-policy-revision.sql text eol=lf

.github/workflows/ci.yml

@@ -41,6 +41,8 @@ jobs:
         run: pnpm module:verify
       - name: Test App Kit authoring contracts
         run: pnpm --filter @deft/app-kit test
+      - name: Test shared authority and resource contracts
+        run: pnpm --filter @deft/shared test
       - name: Verify release publishing contract
         run: pnpm test:release-workflow
       - name: Verify container process supervision
@@ -68,6 +70,14 @@ jobs:
           'src/app/(app)/notes/note-save-coordinator.test.ts'
           'src/app/(app)/notes/protected-note-image.test.ts'
           'src/app/(app)/notes/note-load-state.test.ts'
+      - name: Test installed app session and review contracts
+        run: >-
+          pnpm --filter @deft/web exec tsx --test
+          src/lib/app-experience-*.test.ts
+          src/lib/app-runtime-setup.test.ts
+          src/lib/private-state-adoption.test.ts
+          src/lib/action-batch-review.test.ts
+          src/lib/app-navigation.test.ts
       - name: Type check API
         run: pnpm --filter @deft/api typecheck
       - name: Type check Web

Dockerfile

@@ -30,13 +30,17 @@ ARG NEXT_PUBLIC_API_URL=__DEFT_API_URL__
 ARG NEXT_PUBLIC_WS_URL=__DEFT_WS_URL__
 ARG NEXT_PUBLIC_FEATURE_HUDDLES=false
 ARG NEXT_PUBLIC_FEATURE_APPS=false
+ARG NEXT_PUBLIC_FEATURE_APP_RESOURCE_SYNC=false
+ARG NEXT_PUBLIC_FEATURE_APP_ATTACHMENT_BROKER=false
 ARG NEXT_PUBLIC_DEFT_SELF_HOSTED=false
 ARG DEFT_RELEASE_VERSION=0.3.0-preview.14
 ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
 ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
 ENV NEXT_PUBLIC_WS_URL=$NEXT_PUBLIC_WS_URL
 ENV NEXT_PUBLIC_FEATURE_HUDDLES=$NEXT_PUBLIC_FEATURE_HUDDLES
 ENV NEXT_PUBLIC_FEATURE_APPS=$NEXT_PUBLIC_FEATURE_APPS
+ENV NEXT_PUBLIC_FEATURE_APP_RESOURCE_SYNC=$NEXT_PUBLIC_FEATURE_APP_RESOURCE_SYNC
+ENV NEXT_PUBLIC_FEATURE_APP_ATTACHMENT_BROKER=$NEXT_PUBLIC_FEATURE_APP_ATTACHMENT_BROKER
 ENV NEXT_PUBLIC_DEFT_SELF_HOSTED=$NEXT_PUBLIC_DEFT_SELF_HOSTED
 ENV DEFT_RELEASE_VERSION=$DEFT_RELEASE_VERSION
 

apps/api/src/index.ts

@@ -69,10 +69,34 @@ import { skillsRoutes } from './routes/skills.js';
 import { taskTemplateRoutes } from './routes/task-templates.js';
 import { workIntentRoutes } from './routes/work-intents.js';
 import { moduleRoutes } from './routes/modules.js';
+import { resourceRoutes } from './routes/resources.js';
 import { appRoutes } from './routes/apps.js';
 import { appActionRoutes } from './routes/app-actions.js';
 import { appRunRoutes } from './routes/app-runs.js';
 import { appDeveloperRoutes } from './routes/app-developer.js';
+import { appRuntimeChannelRoutes } from './routes/app-runtime-channel.js';
+import { appAttachmentSyncChannelRoutes } from './routes/app-attachment-sync-channel.js';
+import { appResourceSyncChannelRoutes } from './routes/app-resource-sync-channel.js';
+import { appResourceSyncLimits } from './middleware/app-resource-sync-limits.js';
+import { appRuntimeManagementRoutes } from './routes/app-runtime-management.js';
+import { appResourceSyncManagementRoutes } from './routes/app-resource-sync-management.js';
+import { appResourceAccessRoutes } from './routes/app-resource-access.js';
+import { appAttachmentOwnerRoutes } from './routes/app-attachments.js';
+import { appPrivateMcpRoutes } from './routes/app-private-mcp.js';
+import { appPrivateDeftyRoutes } from './routes/app-private-defty.js';
+import { appResourcePrivateReadRoutes } from './routes/app-resource-private-read.js';
+import { appResourcePrivateReadLimits, appResourceSyncManagementLimits, createAppResourcePrivateReadLimits } from './middleware/app-resource-private-limits.js';
+import { appRuntimeReviewRoutes } from './routes/app-runtime-review.js';
+import { appRuntimeActionRoutes } from './routes/app-runtime-actions.js';
+import { appExperienceRoutes } from './routes/app-experiences.js';
+import { createAppActionBatchRoutes } from './routes/app-action-batches.js';
+import { createExperienceHumanActionRoutes } from './lib/app-experience-human-action-routes.js';
+import { AppExperienceHumanActionService } from './lib/app-experience-human-action-service.js';
+import { AppExperienceExposureService } from './lib/app-experience-exposure.js';
+import { getAppRunRuntime } from './lib/app-run-runtime.js';
+import { createAppPublicRoutes } from './routes/app-public.js';
+import { AppPublicClaimService } from './lib/app-public-service.js';
+import { appPublicManagementRoutes } from './routes/app-public-management.js';
 import { APPS_ENABLED, APP_DEVELOPER_PAIRING_ENABLED } from './lib/env.js';
 import { moduleTaskLinkRoutes } from './routes/module-task-links.js';
 import { authMiddleware } from './middleware/auth.js';
@@ -108,6 +132,7 @@ app.use('*', cors({
     'Mcp-Name',
   ],
   allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  exposeHeaders: ['Content-Disposition', 'X-Content-Type-Options'],
 }));
 
 // Task 4 (private-alpha): security headers. Browsers loading API responses
@@ -184,6 +209,32 @@ if (APP_DEVELOPER_PAIRING_ENABLED) {
   app.use('/api/app-developer/*', authLimiter);
   app.route('/api/app-developer', appDeveloperRoutes);
 }
+// Runtime credentials have a separate audience; never accept browser cookies.
+if (APPS_ENABLED) {
+  app.use('/api/app-runtime/channel/*', authLimiter);
+  app.route('/api/app-runtime/channel', appRuntimeChannelRoutes);
+  app.use('/api/app-resource-sync/channel/*', appResourceSyncLimits);
+  app.use('/api/app-resource-sync-channel/v3/*',appResourceSyncLimits);
+  app.route('/api/app-resource-sync-channel/v3',appAttachmentSyncChannelRoutes);
+  app.route('/api/app-resource-sync/channel', appResourceSyncChannelRoutes);
+  // Owner controls and private reads verify a live web SID themselves. Employee
+  // and Runtime credentials must never reach these human-only surfaces.
+  app.use('/api/app-resource-sync-management/*', appResourceSyncManagementLimits);
+  app.route('/api/app-resource-sync-management', appResourceSyncManagementRoutes);
+  app.use('/api/app-resource-private/*', appResourcePrivateReadLimits);
+  app.use('/api/private-resources/*',appResourcePrivateReadLimits);
+  app.route('/api/private-resources',appAttachmentOwnerRoutes);
+  app.route('/api/app-resource-private', appResourcePrivateReadRoutes);
+  app.use('/api/app-resource-access/*', createAppResourcePrivateReadLimits());
+  app.route('/api/app-resource-access', appResourceAccessRoutes);
+  app.use('/api/app-private-mcp/*', createAppResourcePrivateReadLimits());
+  app.route('/api/app-private-mcp', appPrivateMcpRoutes);
+  app.use('/api/apps/private-defty/*', createAppResourcePrivateReadLimits());
+  app.route('/api/apps/private-defty', appPrivateDeftyRoutes);
+}
+if (APPS_ENABLED && process.env.DEFT_APP_PUBLIC_INGRESS_ENABLED === 'true') {
+  app.route('/api/public/apps', createAppPublicRoutes(new AppPublicClaimService({ enabled: true })));
+}
 app.use('/api/*', authMiddleware);
 app.use('/api/*', defaultLimiter);
 app.use('/api/agent/*', agentLimiter);
@@ -245,6 +296,17 @@ app.route('/api/task-templates', taskTemplateRoutes);
 app.route('/api/work-intents', workIntentRoutes);
 app.route('/api/modules', moduleRoutes);
 if (APPS_ENABLED) {
+  app.route('/api/resources', resourceRoutes);
+  app.route('/api/apps/public', appPublicManagementRoutes);
+  app.route('/api/apps/runtime', appRuntimeManagementRoutes);
+  app.route('/api/app-runtime-review', appRuntimeReviewRoutes);
+  app.route('/api/app-runtime-actions', appRuntimeActionRoutes);
+  app.route('/api/app-experiences', appExperienceRoutes);
+  app.route('/api/app-action-batches', createAppActionBatchRoutes());
+  app.route('/api/app-experiences', createExperienceHumanActionRoutes(async () => {
+    const runtime = await getAppRunRuntime();
+    return new AppExperienceHumanActionService(new AppExperienceExposureService(runtime.keys), runtime);
+  }));
   app.route('/api/apps', appRoutes);
   app.route('/api/app-actions', appActionRoutes);
   app.route('/api/app-runs', appRunRoutes);

apps/api/src/lib/agent-approval-resolver.ts

@@ -1,3 +1,4 @@
+import type { AppRunTransaction } from './app-run-repository.js';
 /**
  * Phase 6.5 — approval resolver.
  *
@@ -820,7 +821,7 @@ async function dispatchAction(
 export async function approveAction(
   actionId: string,
   approverUserId: string,
-  options: { internal?: boolean } = {},
+  options: { internal?: boolean; appRunFinalGuard?: (tx: AppRunTransaction) => Promise<void> } = {},
 ): Promise<ApprovalResolverResult> {
   const result = await withDbAdvisoryLock(
     `agent-approval:${actionId}`,
@@ -835,7 +836,7 @@ export async function approveAction(
 async function approveActionLocked(
   actionId: string,
   approverUserId: string,
-  options: { internal?: boolean },
+  options: { internal?: boolean; appRunFinalGuard?: (tx: AppRunTransaction) => Promise<void> },
 ): Promise<ApprovalResolverResult> {
   // Pre-checks read immutable fields so they are safe to run before the
   // atomic claim. If any pre-check fails we return without ever flipping
@@ -884,7 +885,7 @@ async function approveActionLocked(
   }
 
   if (row.action === APP_RUN_APPROVAL_ACTION) {
-    return (await appRunApprovalResolver()).approve(actionId, approverUserId);
+    return (await appRunApprovalResolver()).approve(actionId, approverUserId, options.appRunFinalGuard);
   }
 
   const resumesApprovedModule = isModuleMutation