fix(dashboard): slide a drag back when a read-only folder refuses it

A drop a read-only shared folder refused left the drag chip to vanish
where it was let go, as if something had happened. It now slides back
to where the drag began, as any drop that doesn't land does.

AGENTS.md

@@ -184,7 +184,6 @@ Recipes are tested, copy-pasteable patterns for a task, one layer above the per-
 - **Description.** Written for someone who has never heard of Puter. Start with "Learn how to", put the action first, and say what the reader's app gains: "Learn how to add file sharing to your app with Puter.js, so users can share files in their Puter account with other people." No API names, no mechanism, no list of example cases, and no "not just …" contrast.
 - **Intro.** Explain the situation and why you'd do this, tied to something the reader already knows ("`puter.kv` is your database in Puter.js"). No "Use this when" bullet list.
 - **Structure.** Get to the first working call as early as possible, then add validation, rate limits, and sign-in after it. Explain a Puter concept the first time it appears, such as what `me.puter` is or that `puter.workers.exec()` opens the Puter sign-in window. Split recipes by what the reader needs, not by technique, and give a family of recipes a shared tag.
-- **Reading order.** A recipe reads top to bottom. Each code block uses only functions and variables from blocks above it, so the reader never has to search further down the page to understand it. Start with a small version that works, and have each section add one case. When a section changes a function from earlier, show the whole new version of that function there. If the code is built up over several sections, end with a `## Full Code` block that has all of it.
 - **Link to the reference for full option lists.** Mention only the options the recipe uses, then link to the function page for the rest ("All the sort options are listed on [`puter.fs.readdir()`](/FS/readdir/)."). A copied list of options, rules, or scopes goes stale when the reference changes.
 - **Limits.** Mention a limit only when it's the reason for a pattern the recipe uses, such as one wildcard subscription instead of one per key, and link to [rate-limits-and-quotas.md](src/docs/src/rate-limits-and-quotas.md) or the function page for the number. Leave out limits that code following the recipe never reaches.
 - **Code.** Platform-neutral: just the code, with top-level `await`. No `<script>` or `<html>` wrapper, no IIFE.

doc/pagination.md

@@ -51,10 +51,7 @@ two pages can't be decoded into how fast the table grows; `openCursor` still
 reads a plain cursor. What a cursor wraps is an implementation detail per
 store:
 
-- DynamoDB-backed lists wrap `LastEvaluatedKey`. A kv listing of another
-  namespace (cross-app or through a share handle) resumes after the last entry
-  it returned instead, since the scan can stop on a private one, and its cursor
-  is sealed to that listing and padded to one length.
+- DynamoDB-backed lists wrap `LastEvaluatedKey`.
 - SQL-backed lists wrap a keyset position — `(sortValue, id)` of the last
   row — and the query seeks past it (`WHERE (col, id) > (?, ?) ORDER BY col,
   id`). Any SQL list gaining a cursor must have a deterministic `ORDER BY`

package-lock.json

@@ -19099,7 +19099,7 @@
     },
     "src/puter-js": {
       "name": "@heyputer/puter.js",
-      "version": "2.6.5",
+      "version": "2.6.4",
       "license": "Apache-2.0",
       "dependencies": {
         "@heyputer/kv.js": "^0.2.1",

src/backend/clients/database/SqliteDatabaseClient.test.ts

@@ -27,7 +27,7 @@ import { DatabaseClientFactory } from './index.js';
 import { SqliteDatabaseClient } from './SqliteDatabaseClient.js';
 
 /** Highest schema version the migration table can reach. */
-const CURRENT_SCHEMA_VERSION = 91;
+const CURRENT_SCHEMA_VERSION = 90;
 
 /**
  * These suites migrate real files on disk. Idle they finish in well under a

src/backend/clients/database/SqliteDatabaseClient.ts

@@ -129,7 +129,6 @@ const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [87, ['0092_share-entry-owner.sql']],
     [88, ['0093_fsentries-parent-uid-index.sql']],
     [89, ['0094_deleted-apps.sql']],
-    [90, ['0095_kv-share-handle-levels.sql']],
 ];
 
 export class SqliteDatabaseClient extends AbstractDatabaseClient {

src/backend/clients/database/migrations/mysql/mysql_mig_49.sql

@@ -1,50 +0,0 @@
--- Copyright (C) 2024-present Puter Technologies Inc.
---
--- This file is part of Puter.
---
--- Puter is free software: you can redistribute it and/or modify
--- it under the terms of the GNU Affero General Public License as published
--- by the Free Software Foundation, either version 3 of the License, or
--- (at your option) any later version.
---
--- This program is distributed in the hope that it will be useful,
--- but WITHOUT ANY WARRANTY; without even the implied warranty of
--- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
--- GNU Affero General Public License for more details.
---
--- You should have received a copy of the GNU Affero General Public License
--- along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
--- Share levels on `kv_share_handles`. See
--- sqlite/0095_kv-share-handle-levels.sql for the rationale. No per-file
--- applied-state tracking, so every step is guarded and a replay does nothing.
-
-CALL _puter_add_col('kv_share_handles', 'revoked_by', '`revoked_by` varchar(8) DEFAULT NULL');
-CALL _puter_add_col('kv_share_handles', 'label', '`label` varchar(512) DEFAULT NULL');
-
-DROP PROCEDURE IF EXISTS _puter_add_kv_share_handle_indexes;
-DELIMITER //
-CREATE PROCEDURE _puter_add_kv_share_handle_indexes()
-BEGIN
-  IF NOT EXISTS (
-    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
-    WHERE TABLE_SCHEMA = DATABASE()
-      AND TABLE_NAME = 'kv_share_handles'
-      AND INDEX_NAME = 'idx_kv_share_handles_grantee'
-  ) THEN
-    ALTER TABLE `kv_share_handles` ADD INDEX `idx_kv_share_handles_grantee` (`grantee_user_id`, `id`);
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
-    WHERE TABLE_SCHEMA = DATABASE()
-      AND TABLE_NAME = 'kv_share_handles'
-      AND INDEX_NAME = 'idx_kv_share_handles_app'
-  ) THEN
-    ALTER TABLE `kv_share_handles` ADD INDEX `idx_kv_share_handles_app` (`app_uid`);
-  END IF;
-END//
-DELIMITER ;
-
-CALL _puter_add_kv_share_handle_indexes();
-
-DROP PROCEDURE IF EXISTS _puter_add_kv_share_handle_indexes;

src/backend/clients/database/migrations/postgres/postgres_mig_38.sql

@@ -1,29 +0,0 @@
--- Copyright (C) 2024-present Puter Technologies Inc.
---
--- This file is part of Puter.
---
--- Puter is free software: you can redistribute it and/or modify
--- it under the terms of the GNU Affero General Public License as published
--- by the Free Software Foundation, either version 3 of the License, or
--- (at your option) any later version.
---
--- This program is distributed in the hope that it will be useful,
--- but WITHOUT ANY WARRANTY; without even the implied warranty of
--- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
--- GNU Affero General Public License for more details.
---
--- You should have received a copy of the GNU Affero General Public License
--- along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
--- Share levels on kv_share_handles. See
--- sqlite/0095_kv-share-handle-levels.sql for the rationale. Idempotent via
--- IF NOT EXISTS; there is no per-file applied-state tracking.
-
-ALTER TABLE kv_share_handles ADD COLUMN IF NOT EXISTS revoked_by VARCHAR(8) DEFAULT NULL;
-ALTER TABLE kv_share_handles ADD COLUMN IF NOT EXISTS label VARCHAR(512) DEFAULT NULL;
-
-CREATE INDEX IF NOT EXISTS idx_kv_share_handles_grantee
-    ON kv_share_handles (grantee_user_id, id);
-
-CREATE INDEX IF NOT EXISTS idx_kv_share_handles_app
-    ON kv_share_handles (app_uid);

src/backend/clients/database/migrations/sqlite/0095_kv-share-handle-levels.sql

@@ -1,35 +0,0 @@
--- Copyright (C) 2024-present Puter Technologies Inc.
---
--- This file is part of Puter.
---
--- Puter is free software: you can redistribute it and/or modify
--- it under the terms of the GNU Affero General Public License as published
--- by the Free Software Foundation, either version 3 of the License, or
--- (at your option) any later version.
---
--- This program is distributed in the hope that it will be useful,
--- but WITHOUT ANY WARRANTY; without even the implied warranty of
--- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
--- GNU Affero General Public License for more details.
---
--- You should have received a copy of the GNU Affero General Public License
--- along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
--- What share levels need from `kv_share_handles`. The level itself is not a
--- column: it is the root of the stored `permission`.
---
---   - `revoked_by` : `owner`, `holder` or `system` (the namespace app was
---                    deleted). Null while live, and on rows retired before
---                    this existed.
---   - `label`      : optional owner-set text the holder is shown.
---   - the grantee index serves the holder's listing and their unshare, and
---     the app index retiring a deleted app's handles.
-
-ALTER TABLE `kv_share_handles` ADD COLUMN `revoked_by` TEXT DEFAULT NULL;
-ALTER TABLE `kv_share_handles` ADD COLUMN `label` TEXT DEFAULT NULL;
-
-CREATE INDEX IF NOT EXISTS `idx_kv_share_handles_grantee`
-    ON `kv_share_handles` (`grantee_user_id`, `id`);
-
-CREATE INDEX IF NOT EXISTS `idx_kv_share_handles_app`
-    ON `kv_share_handles` (`app_uid`);

src/backend/clients/dynamodb/DDBClient.test.ts

@@ -188,47 +188,6 @@ describe('DDBClient — item operations', () => {
         ).toBeUndefined();
     });
 
-    it('puts only while its condition holds', async () => {
-        const absent = {
-            expression: 'attribute_not_exists(#pk)',
-            names: { '#pk': 'pk' },
-        };
-        await client.put(
-            TABLE,
-            { pk: 'u7', sk: 'once', v: 1 },
-            {
-                condition: absent,
-            },
-        );
-        await expect(
-            client.put(
-                TABLE,
-                { pk: 'u7', sk: 'once', v: 2 },
-                {
-                    condition: absent,
-                },
-            ),
-        ).rejects.toMatchObject({ name: 'ConditionalCheckFailedException' });
-        expect(
-            (await client.get(TABLE, { pk: 'u7', sk: 'once' })).Item?.v,
-        ).toBe(1);
-
-        await client.put(
-            TABLE,
-            { pk: 'u7', sk: 'once', v: 3 },
-            {
-                condition: {
-                    expression: '#v = :held',
-                    names: { '#v': 'v' },
-                    values: { ':held': 1 },
-                },
-            },
-        );
-        expect(
-            (await client.get(TABLE, { pk: 'u7', sk: 'once' })).Item?.v,
-        ).toBe(3);
-    });
-
     it('fetches keys from several tables in one batch', async () => {
         await client.put(TABLE, { pk: 'b1', sk: 'a', v: 1 });
         await client.put(TABLE, { pk: 'b1', sk: 'b', v: 2 });

src/backend/clients/dynamodb/DDBClient.ts

@@ -252,19 +252,7 @@ export class DDBClient extends PuterClient {
     }
 
     @Span('ddb.put', (table: string) => ({ 'db.table': table }))
-    async put<T extends Record<string, unknown>>(
-        table: string,
-        item: T,
-        opts?: {
-            /** Refused (`ConditionalCheckFailedException`) unless it holds. */
-            condition?: {
-                expression: string;
-                names?: Record<string, string>;
-                values?: Record<string, unknown>;
-            };
-        },
-    ) {
-        const condition = opts?.condition;
+    async put<T extends Record<string, unknown>>(table: string, item: T) {
         const client = await this.#getDocumentClient();
         return sendRepairingValues(
             item,
@@ -274,23 +262,6 @@ export class DDBClient extends PuterClient {
                         TableName: table,
                         Item: itemToWrite,
                         ReturnConsumedCapacity: 'TOTAL',
-                        ...(condition
-                            ? {
-                                  ConditionExpression: condition.expression,
-                                  ...(condition.names
-                                      ? {
-                                            ExpressionAttributeNames:
-                                                condition.names,
-                                        }
-                                      : {}),
-                                  ...(condition.values
-                                      ? {
-                                            ExpressionAttributeValues:
-                                                condition.values,
-                                        }
-                                      : {}),
-                              }
-                            : {}),
                     }),
                 ),
             () => `a put to ${table}`,

src/backend/clients/event/types.ts

@@ -397,8 +397,6 @@ export type EventMap = {
         user_id: number;
         user_uuid?: string;
         stripe_customer_id?: string | null;
-        /** Apps the account owned, which cascaded away with it. */
-        appUids?: string[];
     };
 
     // ---- Team billing ---- the trigger, never the charge ----
@@ -492,33 +490,13 @@ export type EventMap = {
         noShareKeys?: string[];
         /** Events handler runs behind the write; see `Actor.handlerDepth`. */
         handlerDepth?: number;
-        /**
-         * The user who made the change. Differs from `userId` when a share
-         * holder wrote into the owner's namespace.
-         */
-        actingUserId?: number;
-        /** Made by a worker session or an events handler; see `viaWorkerOf`. */
-        viaWorker?: true;
     };
     /**
      * A whole namespace was emptied. Namespace-level on purpose: `flush`'s own
      * key enumeration is truncated for a large namespace, so the keys it saw
      * are not the keys it removed.
      */
-    'kv.flushed': {
-        namespace: string;
-        userId: number;
-        actingUserId?: number;
-        viaWorker?: true;
-    };
-    /**
-     * Share handles stopped being addresses, whoever retired them. `userId` is
-     * one user who could have subscribed through them, their owner or their
-     * holder. Listeners end what was made through them even where another grant
-     * still covers the region. Local, like `permission.revoked`: one region
-     * settling covers every other.
-     */
-    'kv.share.retired': { handles: string[]; userId: number };
+    'kv.flushed': { namespace: string; userId: number };
 
     // ---- Notifications ----
     /**

src/backend/controllers/auth/AuthController.test.ts

@@ -49,7 +49,7 @@ import {
 } from '../../core/http/types.js';
 import { PuterServer } from '../../server.js';
 import { createSecret as otpCreateSecret } from '../../services/auth/OTPUtil.js';
-import { kvSharePermission } from '../../services/kvShare/kvShares.js';
+import { kvSharePermission } from '../../services/events/kvShares.js';
 import { FULL_API_ACCESS } from '../../services/permission/consts.js';
 import { setupTestServer } from '../../testUtil.js';
 import { resetCardVerificationStatusCache } from '../../util/cardFallback.js';
@@ -2151,7 +2151,7 @@ describe('AuthController grant flows', () => {
             },
             { ownerUserId: issuer.id },
         );
-        const permission = `events:background`;
+        const permission = `service:tg-app:ii:read`;
         // The controller's grant call delegates through PermissionService
         // (which uses ALS Context.set), so wrap in runWithContext.
         const res = makeRes();
@@ -2192,7 +2192,7 @@ describe('AuthController grant flows', () => {
             },
             { ownerUserId: issuer.id },
         );
-        const permission = `events:background`;
+        const permission = `service:tg-origin-app:ii:read`;
         const res = makeRes();
         await inCtx(issuerActor, () =>
             controller.handleGrantUserApp(
@@ -2229,7 +2229,7 @@ describe('AuthController grant flows', () => {
             },
             { ownerUserId: issuer.id },
         );
-        const permission = `events:background`;
+        const permission = `service:tr-origin-app:ii:read`;
         await inCtx(issuerActor, () =>
             controller.handleGrantUserApp(
                 makeReq(
@@ -2294,7 +2294,7 @@ describe('AuthController grant flows', () => {
         await inCtx(issuerActor, () =>
             controller.handleRevokeUserApp(
                 makeReq(
-                    { app_uid: app.uid, permission: 'events:background' },
+                    { app_uid: app.uid, permission: 'service:x:ii:read' },
                     { actor: issuerActor },
                 ),
                 makeRes(),
@@ -2318,12 +2318,12 @@ describe('AuthController grant flows', () => {
 
     it('grant-user-app: 400 on non-string or oversized origin/app_uid/permission', async () => {
         const cases = [
-            { origin: { host: 'evil' }, permission: 'events:background' },
-            { origin: 'https://a.test', permission: ['events:background'] },
-            { app_uid: 12345, permission: 'events:background' },
+            { origin: { host: 'evil' }, permission: 'service:x:ii:read' },
+            { origin: 'https://a.test', permission: ['service:x:ii:read'] },
+            { app_uid: 12345, permission: 'service:x:ii:read' },
             {
                 origin: `https://${'a'.repeat(5000)}.test`,
-                permission: 'events:background',
+                permission: 'service:x:ii:read',
             },
         ];
         for (const body of cases) {
@@ -2354,7 +2354,7 @@ describe('AuthController grant flows', () => {
             { ownerUserId: target.id },
         );
 
-        const permission = 'events:background';
+        const permission = 'service:squat:ii:read';
         for (const handler of [
             'handleGrantUserApp',
             'handleRevokeUserApp',
@@ -2398,7 +2398,7 @@ describe('AuthController grant flows', () => {
             { ownerUserId: target.id },
         );
 
-        const permission = 'events:background';
+        const permission = 'service:squat-beside:ii:read';
         for (const handler of [
             'handleGrantUserApp',
             'handleRevokeUserApp',
@@ -2451,7 +2451,7 @@ describe('AuthController grant flows', () => {
             { ownerUserId: issuer.id },
         );
 
-        const permission = 'events:background';
+        const permission = 'service:tp-origin:ii:read';
         await inCtx(issuerActor, () =>
             controller.handleGrantUserApp(
                 makeReq(
@@ -2487,7 +2487,7 @@ describe('AuthController grant flows', () => {
             },
             { ownerUserId: issuer.id },
         );
-        const permission = 'events:background';
+        const permission = 'service:tm-app:ii:read';
         for (const body of [
             { app_uid: app.uid, permission, meta: 'nope' },
             { app_uid: app.uid, permission, meta: [1, 2] },
@@ -2528,7 +2528,7 @@ describe('AuthController grant flows', () => {
             },
             { ownerUserId: issuer.id },
         );
-        const permission = 'events:background';
+        const permission = 'service:tb-app:ii:read';
         const oversized = { blob: 'z'.repeat(5000) };
         for (const body of [
             { app_uid: app.uid, permission, extra: oversized },
@@ -2605,278 +2605,26 @@ describe('AuthController grant flows', () => {
         expect(res.body).toEqual({});
     });
 
-    it('grant-user-app: grants read and write share delegations on a region, never on the namespace', async () => {
-        const appName = `tkvl-${uuidv4()}`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestKvShareLevelsApp',
-                index_url: `https://${appName}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        for (const root of ['kv-share-read', 'kv-share-write']) {
-            const namespace = `manage:${root}:${issuer.uuid}:${app.uid}`;
-            await expect(
-                inCtx(issuerActor, () =>
-                    controller.handleGrantUserApp(
-                        makeReq(
-                            { app_uid: app.uid, permission: namespace },
-                            { actor: issuerActor },
-                        ),
-                        makeRes(),
-                    ),
-                ),
-            ).rejects.toMatchObject({ legacyCode: 'invalid_kv_share_prefix' });
-
-            const res = makeRes();
-            await inCtx(issuerActor, () =>
-                controller.handleGrantUserApp(
-                    makeReq(
-                        { app_uid: app.uid, permission: `${namespace}:team` },
-                        { actor: issuerActor },
-                    ),
-                    res,
-                ),
-            );
-            expect(res.body).toEqual({});
-        }
-        const rows = await server.clients.db.read(
-            'SELECT `permission` FROM `user_to_app_permissions` WHERE `user_id` = ? AND `app_id` = ? ORDER BY `permission`',
-            [issuer.id, app.id],
-        );
-        expect(rows.map((r: { permission: string }) => r.permission)).toEqual([
-            `manage:kv-share-read:${issuer.uuid}:${app.uid}:team`,
-            `manage:kv-share-write:${issuer.uuid}:${app.uid}:team`,
-        ]);
-    });
-
-    it('grant-user-app: refuses a share delegation whose region a new share could not name, writing nothing', async () => {
-        const appName = `tkvc-${uuidv4()}`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestKvShareCharsApp',
-                index_url: `https://${appName}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        for (const region of ['Team', 'team:Abc', 'caf\u00E9', 'a b'])
-            await expect(
-                inCtx(issuerActor, () =>
-                    controller.handleGrantUserApp(
-                        makeReq(
-                            {
-                                app_uid: app.uid,
-                                permission: `manage:kv-share-read:${issuer.uuid}:${app.uid}:${region}`,
-                            },
-                            { actor: issuerActor },
-                        ),
-                        makeRes(),
-                    ),
-                ),
-            ).rejects.toMatchObject({ legacyCode: 'invalid_kv_share_prefix' });
-        const rows = await server.clients.db.read(
-            'SELECT `permission` FROM `user_to_app_permissions` WHERE `user_id` = ? AND `app_id` = ?',
-            [issuer.id, app.id],
-        );
-        expect(rows).toEqual([]);
-    });
-
-    it('grant-user-app: refuses a permission outside the app-grantable families, writing nothing', async () => {
-        const appName = `tng-${uuidv4()}`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestNotGrantableApp',
-                index_url: `https://${appName}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        const other = await server.stores.app.create(
-            {
-                name: `tng-other-${uuidv4()}`,
-                title: 'TestNotGrantableOther',
-                index_url: `https://tng-other-${uuidv4()}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        const refused = [
-            ['driver:puter-image-generation:generate'],
-            [`user:${target.uuid}:email:read`],
-            // One bad entry refuses the batch.
-            ['events:background', 'random-string'],
-            // A share delegation names the app's own namespace only.
-            [`manage:kv-share:${issuer.uuid}:${other.uid}:rooms`],
-        ];
-        for (const permissions of refused) {
-            await expect(
-                inCtx(issuerActor, () =>
-                    controller.handleGrantUserApp(
-                        makeReq(
-                            { app_uid: app.uid, permissions },
-                            { actor: issuerActor },
-                        ),
-                        makeRes(),
-                    ),
-                ),
-            ).rejects.toMatchObject({
-                statusCode: 400,
-                legacyCode: 'permission_not_grantable',
-            });
-        }
-        const rows = await server.clients.db.read(
-            'SELECT 1 FROM `user_to_app_permissions` WHERE `user_id` = ? AND `app_id` = ?',
-            [issuer.id, app.id],
-        );
-        expect(rows).toEqual([]);
-    });
-
-    it('grant-user-app: refuses a non-canonical spelling of a grantable permission', async () => {
-        const appName = `tnc-${uuidv4()}`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestNonCanonicalApp',
-                index_url: `https://${appName}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        for (const permission of [
-            `f\\s:/${issuer.username}/Documents:read`,
-            `app-root-di\\r:${app.uid}:read`,
-            `manag\\e:kv-share:${issuer.uuid}:${app.uid}:rooms`,
-        ]) {
-            await expect(
-                inCtx(issuerActor, () =>
-                    controller.handleGrantUserApp(
-                        makeReq(
-                            { app_uid: app.uid, permission },
-                            { actor: issuerActor },
-                        ),
-                        makeRes(),
-                    ),
-                ),
-            ).rejects.toMatchObject({ legacyCode: 'permission_not_grantable' });
-        }
-    });
-
-    it('grant-user-app: refuses a share delegation over a prefix no share could be made of, as a share would be', async () => {
-        const appName = `tkvp-${uuidv4().slice(0, 8)}`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestKvSharePrefixApp',
-                index_url: `https://${appName}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        for (const root of ['kv-share', 'kv-share-read', 'kv-share-write']) {
-            // A share grant one character wider than the column.
-            const head = `${root}:${issuer.uuid}:${app.uid}:`;
-            const region = 'a'.repeat(256 - head.length);
-            await expect(
-                inCtx(issuerActor, () =>
-                    controller.handleGrantUserApp(
-                        makeReq(
-                            {
-                                app_uid: app.uid,
-                                permission: `manage:${head}${region}`,
-                            },
-                            { actor: issuerActor },
-                        ),
-                        makeRes(),
-                    ),
-                ),
-            ).rejects.toMatchObject({ legacyCode: 'invalid_kv_share_prefix' });
-        }
-    });
-
-    it('grant-user-app: a share delegation must name the app the request names, by uid, name or origin', async () => {
-        const appName = `tkvn-${uuidv4()}`;
-        const origin = `https://${appName}.example.test`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestKvShareNamedApp',
-                index_url: `${origin}/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        const other = await server.stores.app.create(
-            {
-                name: `tkvn-other-${uuidv4()}`,
-                title: 'TestKvShareNamedOther',
-                index_url: `https://tkvn-other-${uuidv4()}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        const grant = (requester: Record<string, string>, namespace: string) =>
+    it('grant-user-app: 400 on a `permission` wider than the column it lands in', async () => {
+        // 300 chars is under the 4096 input cap but over `varchar(255)`, so it
+        // used to reach the INSERT and fault on MySQL/Postgres. The check runs
+        // after the rewrite, so this has to be a permission no rewriter
+        // shortens — and it has to reject before the app is resolved, since
+        // this uid names no app.
+        await expect(
             inCtx(issuerActor, () =>
                 controller.handleGrantUserApp(
                     makeReq(
                         {
-                            ...requester,
-                            permission: `manage:kv-share:${issuer.uuid}:${namespace}:rooms`,
+                            app_uid: `app-${uuidv4()}`,
+                            permission: `service:${'a'.repeat(300)}:ii:read`,
                         },
                         { actor: issuerActor },
                     ),
                     makeRes(),
                 ),
-            );
-
-        for (const requester of [{ app_uid: app.name }, { origin }]) {
-            await grant(requester, app.uid);
-            await expect(grant(requester, other.uid)).rejects.toMatchObject({
-                legacyCode: 'permission_not_grantable',
-            });
-        }
-        // The app's name is not its namespace.
-        await expect(
-            grant({ app_uid: app.uid }, app.name),
-        ).rejects.toMatchObject({ legacyCode: 'permission_not_grantable' });
-        const rows = await server.clients.db.read(
-            'SELECT `permission` FROM `user_to_app_permissions` WHERE `user_id` = ? AND `app_id` = ?',
-            [issuer.id, app.id],
-        );
-        expect(rows.map((r: { permission: string }) => r.permission)).toEqual([
-            `manage:kv-share:${issuer.uuid}:${app.uid}:rooms`,
-        ]);
-    });
-
-    it('grant-user-app: 400 on a `permission` wider than the column it lands in', async () => {
-        // Under the 4096 input cap but over `varchar(255)`, so it would reach
-        // the INSERT and fault on MySQL/Postgres. The check runs after the
-        // rewrite, so this has to be a grantable permission no rewriter
-        // shortens.
-        const appName = `tw-${uuidv4()}`;
-        const app = await server.stores.app.create(
-            {
-                name: appName,
-                title: 'TestWidthApp',
-                index_url: `https://${appName}.example.test/index.html`,
-            },
-            { ownerUserId: issuer.id },
-        );
-        // The shares it delegates fit, at 255 characters; the consent's own
-        // `manage:` arm takes it past the column.
-        const head = `kv-share:${issuer.uuid}:${app.uid}:`;
-        const permission = `manage:${head}${'a'.repeat(255 - head.length)}`;
-        await expect(
-            inCtx(issuerActor, () =>
-                controller.handleGrantUserApp(
-                    makeReq(
-                        { app_uid: app.uid, permission },
-                        { actor: issuerActor },
-                    ),
-                    makeRes(),
-                ),
             ),
-        ).rejects.toMatchObject({
-            statusCode: 400,
-            legacyCode: 'bad_request',
-            message: 'Invalid `permission`',
-        });
+        ).rejects.toMatchObject({ statusCode: 400 });
     });
 
     it('grant-user-app: an oversized permission that a rewriter shortens is accepted', async () => {
@@ -2888,8 +2636,6 @@ describe('AuthController grant flows', () => {
         // on "please try again" for any deeply nested file. Exercised here
         // through a rewriter of our own, since the real fs rewriter resolves
         // the path through the fsentry store and this suite has no entries.
-        // It rewrites a share delegation only because that is a grantable
-        // shape no production rewriter touches.
         const appName = `tlp-${uuidv4()}`;
         const app = await server.stores.app.create(
             {
@@ -2900,15 +2646,13 @@ describe('AuthController grant flows', () => {
             { ownerUserId: issuer.id },
         );
 
-        // Over the column only by its `manage:` arm, so the shares it
-        // delegates still fit.
-        const head = `kv-share:${issuer.uuid}:${app.uid}:`;
-        const longPermission = `manage:${head}${'a'.repeat(255 - head.length)}`;
-        const shortPermission = `manage:${head}${uuidv4()}`;
+        const prefix = `tlprw-${uuidv4()}`;
+        const longPermission = `${prefix}:${'a'.repeat(300)}:read`;
+        const shortPermission = `${prefix}:${uuidv4()}:read`;
         expect(longPermission.length).toBeGreaterThan(255);
         expect(shortPermission.length).toBeLessThanOrEqual(255);
         server.services.permission.registerRewriter({
-            id: `test-shorten-${app.uid}`,
+            id: `test-shorten-${prefix}`,
             matches: (permission: string) => permission === longPermission,
             rewrite: async () => shortPermission,
         });
@@ -2968,8 +2712,7 @@ describe('AuthController grant flows', () => {
             { ownerUserId: issuer.id },
         );
 
-        // A grantable shape no production rewriter touches.
-        const prefix = `manage:kv-share:${issuer.uuid}:${app.uid}:conc-${uuidv4()}`;
+        const prefix = `conc-${uuidv4()}`;
         let release: () => void;
         let entered: () => void;
         const held = new Promise<void>((r) => {
@@ -2997,7 +2740,7 @@ describe('AuthController grant flows', () => {
                 makeReq(
                     {
                         app_uid: app.uid,
-                        permission: `${prefix}:write`,
+                        permission: `${prefix}:${app.uid}:write`,
                     },
                     { actor: issuerActor },
                 ),
@@ -3038,8 +2781,8 @@ describe('AuthController grant flows', () => {
             { ownerUserId: issuer.id },
         );
 
-        const prefix = `manage:kv-share:${issuer.uuid}:${app.uid}:tardrw-${uuidv4()}`;
-        const pseudoPermission = `${prefix}:write`;
+        const prefix = `tardrw-${uuidv4()}`;
+        const pseudoPermission = `${prefix}:${app.uid}:write`;
         const resolvedPermission = `fs:${uuidv4()}:write`;
         const NOTHING = 'nothing-in-particular';
         server.services.permission.registerRewriter({
@@ -3280,7 +3023,7 @@ describe('AuthController.handleGrantUserApp `create` flag', () => {
         // phase A's pre-flight passes, phase C's re-check then fails, so the
         // leaf (and its auto-created parent) already exist by the time the
         // request unwinds.
-        const prefix = `manage:kv-share:${user.uuid}:${appUid}:rbparent-${uuidv4()}`;
+        const prefix = `rbparent-${uuidv4()}`;
         let calls = 0;
         server.services.permission.registerRewriter({
             id: prefix,
@@ -3446,13 +3189,13 @@ describe('AuthController.handleGrantUserApp `create` flag', () => {
         ).rejects.toMatchObject({ statusCode: 400, legacyCode: 'bad_request' });
     });
 
-    it('refuses a `manage:` grant outright, creating nothing', async () => {
+    it('does not apply `create` to a `manage:` grant — 404 unchanged, nothing created', async () => {
         const p = path(`manage-missing-${rand()}`);
         await expect(
             grant({ permission: `manage:fs:${p}:write` }),
         ).rejects.toMatchObject({
-            statusCode: 400,
-            legacyCode: 'permission_not_grantable',
+            statusCode: 404,
+            legacyCode: 'subject_does_not_exist',
         });
         expect(await server.stores.fsEntry.getEntryByPath(p)).toBeFalsy();
     });
@@ -3542,7 +3285,7 @@ describe('AuthController.handleGrantUserApp `create` flag', () => {
         // (so nothing is rejected before anything is created) but has grown
         // too wide by the time phase C re-runs it — modelling a grant that
         // only fails once the fs path from the same batch already exists.
-        const prefix = `manage:kv-share:${user.uuid}:${appUid}:rbtest-${uuidv4()}`;
+        const prefix = `rbtest-${uuidv4()}`;
         let calls = 0;
         server.services.permission.registerRewriter({
             id: `test-rollback-${prefix}`,
@@ -3583,37 +3326,6 @@ describe('AuthController.handleGrantUserApp `create` flag', () => {
         );
     });
 
-    it('check-permissions answers an app asking about itself through ACL, so a folder grant covers what is inside', async () => {
-        const dir = path(`acl-self-${rand()}`);
-        const child = `${dir}/inner`;
-        await server.services.fs.mkdir(user.id, {
-            path: child,
-            createMissingParents: true,
-        });
-        expect(await checkAsApp(`fs:${child}:read`)).toBe(false);
-
-        await grant({ permission: `fs:${dir}:write`, create: false });
-        expect(await checkAsApp(`fs:${child}:read`)).toBe(true);
-        expect(await checkAsApp(`fs:${child}:write`)).toBe(true);
-        // Another user's home stays out of reach.
-        expect(await checkAsApp(`fs:/${target.username}/Documents:read`)).toBe(
-            false,
-        );
-    });
-
-    it('check-permissions answers an app asking about itself through ACL for a uid too', async () => {
-        const dir = path(`acl-self-uid-${rand()}`);
-        const child = await server.services.fs.mkdir(user.id, {
-            path: `${dir}/inner`,
-            createMissingParents: true,
-        });
-        expect(await checkAsApp(`fs:${child.uuid}:read`)).toBe(false);
-
-        await grant({ permission: `fs:${dir}:read`, create: false });
-        expect(await checkAsApp(`fs:${child.uuid}:read`)).toBe(true);
-        expect(await checkAsApp(`fs:${child.uuid}:write`)).toBe(false);
-    });
-
     it('check-permissions on a missing fs path answers false rather than 404ing, without poisoning a mixed batch', async () => {
         const missingPath = path(`.checkmissing-${rand()}`);
         // A held fs grant: the owning user holds it implicitly (is-owner), so
@@ -4440,9 +4152,9 @@ describe('AuthController.handleCreateAccessToken + handleRevokeAccessToken', ()
         ['an oversized permission string', ['x'.repeat(4097)]],
         [
             'an oversized `extra`',
-            [['events:background', { a: 'y'.repeat(5000) }]],
+            [['service:x:ii:read', { a: 'y'.repeat(5000) }]],
         ],
-        ['a non-object `extra`', [['events:background', 'nope']]],
+        ['a non-object `extra`', [['service:x:ii:read', 'nope']]],
         ['an empty permission string', ['']],
     ])('rejects %s with 400', async (_label, permissions) => {
         await expect(
@@ -7653,88 +7365,6 @@ describe('AuthController.handleCheckPermissions + handleListPermissions', () =>
         ]);
     });
 
-    it('check-permissions: answers false for share grants, which name what a holder is never told, but not for their manage arm', async () => {
-        const { user: owner, actor: ownerActor } = await makeUserAndActor();
-        const { user: holder, actor: holderActor } = await makeUserAndActor();
-        const region = `notes-${uuidv4().slice(0, 8)}`;
-        const grant = `kv-share-read:${owner.uuid}:os-global:${region}`;
-        await inCtx(ownerActor, () =>
-            server.services.permission.grantUserUserPermission(
-                ownerActor,
-                holder.username,
-                grant,
-            ),
-        );
-        expect(await server.services.permission.check(holderActor, grant)).toBe(
-            true,
-        );
-
-        const asked = [
-            grant,
-            `kv-share:${owner.uuid}:os-global:${region}:inner`,
-            `kv-share-write:${owner.uuid}:os-global:${region}`,
-        ];
-        const res = makeRes();
-        await inCtx(holderActor, () =>
-            controller.handleCheckPermissions(
-                makeReq({ permissions: asked }, { actor: holderActor }),
-                res,
-            ),
-        );
-        expect(res.body).toEqual({
-            permissions: Object.fromEntries(asked.map((p) => [p, false])),
-        });
-
-        // What `puter.perms.check('kvShare', …)` asks.
-        const manage = `manage:kv-share-read:${owner.uuid}:os-global:${region}`;
-        const ownerRes = makeRes();
-        await inCtx(ownerActor, () =>
-            controller.handleCheckPermissions(
-                makeReq({ permissions: [manage] }, { actor: ownerActor }),
-                ownerRes,
-            ),
-        );
-        expect(ownerRes.body).toEqual({ permissions: { [manage]: true } });
-    });
-
-    it('check-permissions: answers false for share grants asked by an app actor too', async () => {
-        const { user: owner, actor: ownerActor } = await makeUserAndActor();
-        const { user: holder, actor: holderActor } = await makeUserAndActor();
-        const app = await server.stores.app.create(
-            {
-                name: `cpk-${uuidv4()}`,
-                title: 'TestCheckPermsKvApp',
-                index_url: 'https://check-perms-kv.example.test/index.html',
-            },
-            { ownerUserId: holder.id },
-        );
-        const grant = `kv-share-read:${owner.uuid}:${app.uid}:notes-${uuidv4().slice(0, 8)}`;
-        await inCtx(ownerActor, () =>
-            server.services.permission.grantUserUserPermission(
-                ownerActor,
-                holder.username,
-                grant,
-            ),
-        );
-        const appActor = makeActor({
-            user: holderActor.user,
-            app: { id: app.id, uid: app.uid },
-        });
-        // The holder's app in the share's namespace holds it.
-        expect(await server.services.permission.check(appActor, grant)).toBe(
-            true,
-        );
-
-        const res = makeRes();
-        await inCtx(appActor, () =>
-            controller.handleCheckPermissions(
-                makeReq({ permissions: [grant] }, { actor: appActor }),
-                res,
-            ),
-        );
-        expect(res.body).toEqual({ permissions: { [grant]: false } });
-    });
-
     // What lets a permission request settle without a prompt. The second string
     // is a consent scope nothing implies, so the first's `true` is the grant.
     it('check-permissions: an app-under-user actor sees a grant made to that app', async () => {
@@ -7949,7 +7579,7 @@ describe('AuthController.handleCheckPermissions + handleListPermissions', () =>
             },
             { ownerUserId: user.id },
         );
-        const permission = 'events:background';
+        const permission = 'service:tl-app:ii:read';
         await inCtx(actor, () =>
             controller.handleGrantUserApp(
                 makeReq({ app_uid: app.uid, permission, extra: {} }, { actor }),
@@ -10585,7 +10215,7 @@ describe('AuthController — app-data grants', () => {
         await expect(
             post('handleGrantUserApp', {
                 app_uid: grantee.uid,
-                permission: `app-data:app-${uuidv4()}:kv:read`,
+                permission: 'app-data:app-nope/:kv:read',
             }),
         ).rejects.toMatchObject({ statusCode: 404 });
     });
@@ -10652,7 +10282,7 @@ describe('AuthController — app-data grants', () => {
 
     it('leaves unrelated permissions untouched by the new validation', async () => {
         const grantee = await makeAppRow();
-        const permission = 'events:background';
+        const permission = 'service:unrelated:ii:read';
         await post('handleGrantUserApp', {
             app_uid: grantee.uid,
             permission,

src/backend/controllers/auth/AuthController.ts

@@ -33,7 +33,7 @@ import {
     hasVerifiedPhone,
 } from '../../core/http/middleware/gates.js';
 import type { Actor } from '../../core/actor.js';
-import { isAppActor, isPlainUserActor, makeActor } from '../../core/actor.js';
+import { isPlainUserActor, makeActor } from '../../core/actor.js';
 import {
     checkRateLimit,
     consumeRouteRateLimit,
@@ -88,16 +88,13 @@ import {
 import { promoteToVerifiedGroup } from '../../util/userProvisioning.js';
 import {
     assertBoundedManageGrant,
-    assertNewShareSegments,
-    assertPrefixFitsAccess,
     isKvSharePermission,
-} from '../../services/kvShare/kvShares.js';
+} from '../../services/events/kvShares.js';
 import {
     APP_DATA_PERMISSION_PREFIX,
     appDataSharingAllowed,
     parseAppDataPermission,
 } from '../../services/permission/appDataScopes.js';
-import { parseAppGrantablePermission } from '../../services/permission/appGrantable.js';
 import {
     assertCreatablePath,
     isOwnHomePath,
@@ -3000,45 +2997,6 @@ export class AuthController extends PuterController {
         return typeof permission === 'string' && permission ? [permission] : [];
     }
 
-    /**
-     * Refuses any entry outside the families an app can be granted. Anything
-     * else is a row the backend never checks for an app, or one wider than the
-     * consent prompt can describe.
-     */
-    async #assertAppGrantable(
-        actor: Actor,
-        appIdentifier: string,
-        list: string[],
-    ): Promise<void> {
-        const refuse = (entry: string) =>
-            new HttpError(
-                400,
-                `Permission cannot be granted to an app: ${entry}`,
-                { legacyCode: 'permission_not_grantable' },
-            );
-        let appUid: string | undefined;
-        for (const entry of list) {
-            // A delegation over a whole key-value namespace has no bounded
-            // description; refused with its own code.
-            assertBoundedManageGrant(entry);
-            const parsed = parseAppGrantablePermission(entry, actor.user!.uuid);
-            if (!parsed) throw refuse(entry);
-            if (parsed.family !== 'kvShare') continue;
-            // Held to what a new share's prefix may be, so a consent never
-            // covers shares that could not be made.
-            assertNewShareSegments(parsed.segments);
-            assertPrefixFitsAccess(
-                parsed.ownerUuid,
-                parsed.appUid,
-                parsed.segments.join(':'),
-                parsed.level,
-            );
-            // An app shares regions of its own namespace only.
-            appUid ??= (await this.stores.app.resolveApp(appIdentifier))?.uid;
-            if (parsed.appUid !== appUid) throw refuse(entry);
-        }
-    }
-
     /**
      * Gate a cross-app data grant: the target must exist, must not have opted
      * out of sharing, and must be named. Also creates the target's AppData
@@ -3217,7 +3175,6 @@ export class AuthController extends PuterController {
         }
         // 400 on a bad value, before anything else runs. Absent means create.
         const create = parseCreateFlag(req.body?.create);
-        await this.#assertAppGrantable(req.actor!, app_uid, list);
 
         // Validate every entry before writing or creating anything, so a bad
         // one in the list cannot leave a partially-granted set behind: the
@@ -3230,6 +3187,10 @@ export class AuthController extends PuterController {
             kind: FsCreateKind;
         }> = [];
         for (const entry of list) {
+            // A delegation over a whole key-value namespace has no bounded
+            // description, so it is refused where it is asked for rather than
+            // prompted for and then refused at use.
+            assertBoundedManageGrant(entry);
             await this.#prepareAppDataGrant(req.actor!, entry);
             const plan = await this.#planFsPathCreate(
                 req.actor!,
@@ -3436,28 +3397,11 @@ export class AuthController extends PuterController {
         const unique = [...new Set(permissions)] as string[];
         const result: Record<string, boolean> = {};
 
-        // A share grant names its owner and prefix, which its holder is never
-        // told, so asking about one would confirm a guess. `manage:` arms are
-        // the app's own consent and stay answerable.
-        const answerable: string[] = [];
-        for (const permission of unique) {
-            if (
-                typeof permission === 'string' &&
-                isKvSharePermission(permission)
-            )
-                result[permission] = false;
-            else answerable.push(permission);
-        }
-
-        // `fs:` reaches down a tree, and only ACL walks that. An app asking
-        // about itself gets the same answer, so a grant on a parent folder
-        // doesn't read as missing and prompt again.
+        // `fs:` reaches down a tree, and only ACL walks that.
         const viaAcl = new Set(
-            app_uid || isAppActor(actor)
-                ? answerable.filter((p) => aclAnswerableFsPermission(p))
-                : [],
+            app_uid ? unique.filter((p) => aclAnswerableFsPermission(p)) : [],
         );
-        const viaScan = answerable.filter((p) => !viaAcl.has(p));
+        const viaScan = unique.filter((p) => !viaAcl.has(p));
 
         let granted: Map<string, boolean>;
         try {

src/backend/controllers/events/EventsController.ts

@@ -154,9 +154,8 @@ export class EventsController extends PuterController {
     // -- Cross-user key-value handles --------------------------------
 
     /**
-     * POST /events/kv-handles — hand another user a region of this account's
-     * key-value data, `watch` unless the body asks for more. The older name for
-     * `POST /kv/shares`, keeping its own body and response shapes.
+     * POST /events/kv-handles — hand another user a watchable region of this
+     * account's key-value data.
      *
      * An account session, or an app session holding a `manage:` delegation on
      * the region — the service tells those apart and gates each rather than the
@@ -168,32 +167,12 @@ export class EventsController extends PuterController {
         subdomain: 'api',
         requireAuth: true,
         allowAccessToken: true,
-        requireVerified: true,
     })
     async mintKvHandle(req: Request, res: Response): Promise<void> {
         const actor = this.#requireActor(req);
-        const body = bodyRecord(req);
-        const share = await this.services.kvShare.mintKvHandle(
-            actor,
-            {
-                prefix: body.prefix,
-                recipient: {
-                    username:
-                        typeof body.granteeUsername === 'string'
-                            ? body.granteeUsername
-                            : undefined,
-                    uid:
-                        typeof body.granteeUid === 'string'
-                            ? body.granteeUid
-                            : undefined,
-                },
-                access: body.access,
-                appUid: body.appUid,
-            },
-            // Callers of this route mint again to get the same handle back.
-            { defaultAccess: 'watch', keepLevelUnlessNamed: true },
+        res.json(
+            await this.services.events.mintKvHandle(actor, bodyRecord(req)),
         );
-        res.json({ handle: share.handle, prefix: share.prefix });
     }
 
     /**
@@ -210,7 +189,7 @@ export class EventsController extends PuterController {
         const actor = this.#requireActor(req);
         const query = (req.query ?? {}) as Record<string, unknown>;
 
-        const page = await this.services.kvShare.listKvHandles(actor, {
+        const page = await this.services.events.listKvHandles(actor, {
             limit: normalizeLimit(query.limit, {
                 cap: KV_HANDLE_LIST_LIMIT_CAP,
             }),
@@ -219,10 +198,7 @@ export class EventsController extends PuterController {
         });
 
         res.json({
-            items: page.items.map(({ holderUsername, ...row }) => ({
-                ...row,
-                granteeUsername: holderUsername,
-            })),
+            items: page.items,
             ...(page.cursor ? { cursor: page.cursor } : {}),
             ...(page.total !== undefined ? { total: page.total } : {}),
         });
@@ -241,10 +217,7 @@ export class EventsController extends PuterController {
     async revokeKvHandle(req: Request, res: Response): Promise<void> {
         const actor = this.#requireActor(req);
         res.json(
-            await this.services.kvShare.revokeKvHandle(
-                actor,
-                req.params.handle,
-            ),
+            await this.services.events.revokeKvHandle(actor, req.params.handle),
         );
     }
 

src/backend/controllers/events/limits.ts

@@ -163,16 +163,6 @@ export const EVENTS_ACK_LIMIT = userWindow('events:ack', 600);
  */
 export const EVENTS_KV_HANDLE_LIMIT = userWindow('events:kvHandles', 60);
 
-/**
- * `kv.share.received` notices per hour, per owner and holder. A share past it
- * is still made, without a notice.
- */
-export const KV_SHARE_NOTICE_LIMIT = userWindow(
-    'kvShare:notices',
-    5,
-    60 * 60_000,
-);
-
 /**
  * Live share handles one account may hold out at a time, across every app.
  *

src/backend/controllers/index.ts

@@ -27,7 +27,6 @@ import { EventsController } from './events/EventsController.js';
 import { FSController } from './fs/FSController.js';
 import { HomepageController } from './homepage/HomepageController.js';
 import { HostingController } from './hosting/HostingController.js';
-import { KvShareController } from './kvShare/KvShareController.js';
 import { LegacyFSController } from './fs/LegacyFSController.js';
 import { NotificationController } from './notification/NotificationController.js';
 import { OIDCController } from './oidc/OIDCController.js';
@@ -59,7 +58,6 @@ export const puterControllers = {
     broadcast: BroadcastController,
     notification: NotificationController,
     events: EventsController,
-    kvShare: KvShareController,
     share: ShareController,
     webdav: WebDAVController,
     oidc: OIDCController,

src/backend/controllers/kvShare/KvShareController.http.test.ts

@@ -1,478 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import {
-    afterAll,
-    beforeAll,
-    beforeEach,
-    describe,
-    expect,
-    it,
-    vi,
-} from 'vitest';
-import {
-    createTestUser,
-    setupPuterTestEnv,
-    type PuterTestEnv,
-    type TestUserCredentials,
-} from '../../testUtil.js';
-import type { IConfig } from '../../types.js';
-import { EVENTS_KV_HANDLE_LIMIT } from '../events/limits.js';
-
-const BOOT_TIMEOUT_MS = 120_000;
-
-const call = (
-    env: PuterTestEnv,
-    method: string,
-    path: string,
-    token?: string,
-    body?: unknown,
-) =>
-    fetch(new URL(path, env.apiOrigin), {
-        method,
-        headers: {
-            'content-type': 'application/json',
-            ...(token ? { authorization: `Bearer ${token}` } : {}),
-        },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-    });
-
-const resetBudgets = async (env: PuterTestEnv) => {
-    for (const name of [env.users.user.username, env.users.other.username]) {
-        const user = await env.server.stores.user.getByUsername(name);
-        await env.server.clients.redis.del(
-            `rate:${EVENTS_KV_HANDLE_LIMIT.scope}:${user!.id}`,
-        );
-    }
-};
-
-describe('/kv/shares', () => {
-    let env: PuterTestEnv;
-    let ownerUuid: string;
-    const req = (
-        method: string,
-        path: string,
-        token?: string,
-        body?: unknown,
-    ) => call(env, method, path, token, body);
-
-    beforeAll(async () => {
-        env = await setupPuterTestEnv({
-            events: { enabled: true, kvHandles: true },
-            kv: { shareHandles: true },
-            unlimitedMetering: true,
-        } as IConfig);
-        const owner = await env.server.stores.user.getByUsername(
-            env.users.user.username,
-        );
-        ownerUuid = owner!.uuid as string;
-    }, BOOT_TIMEOUT_MS);
-
-    afterAll(async () => {
-        await env?.shutdown();
-    });
-
-    beforeEach(async () => {
-        await resetBudgets(env);
-    });
-
-    const shareWithOther = async (body: Record<string, unknown> = {}) => {
-        const res = await req('POST', '/kv/shares', env.users.user.token, {
-            prefix: `http-${uuidv4().slice(0, 8)}:`,
-            recipient: env.users.other.username,
-            ...body,
-        });
-        expect(res.status).toBe(200);
-        return (await res.json()) as Record<string, unknown>;
-    };
-
-    it('shares at read by default and answers in the owner`s shape', async () => {
-        const shared = await shareWithOther({ label: 'Groceries' });
-        expect(Object.keys(shared).sort()).toEqual(
-            [
-                'access',
-                'appUid',
-                'createdAt',
-                'handle',
-                'holder',
-                'label',
-                'prefix',
-            ].sort(),
-        );
-        expect(shared).toMatchObject({
-            access: 'read',
-            appUid: null,
-            holder: env.users.other.username,
-            label: 'Groceries',
-        });
-    });
-
-    it('takes the recipient as an object too, and refuses an address', async () => {
-        await shareWithOther({
-            recipient: { username: env.users.other.username },
-            access: 'write',
-        });
-        const refused = await req('POST', '/kv/shares', env.users.user.token, {
-            prefix: 'address:',
-            recipient: '[email protected]',
-        });
-        expect(refused.status).toBe(400);
-        await expect(refused.json()).resolves.toMatchObject({
-            code: 'invalid_recipient',
-        });
-    });
-
-    it('lists what was shared out, and what was shared with the holder without the owner', async () => {
-        const shared = await shareWithOther({ access: 'write', label: 'Trip' });
-
-        const byMe = await req(
-            'GET',
-            '/kv/shares?limit=200',
-            env.users.user.token,
-        );
-        const byMePage = (await byMe.json()) as {
-            items: Array<Record<string, unknown>>;
-        };
-        expect(
-            byMePage.items.find((row) => row.handle === shared.handle),
-        ).toEqual({
-            handle: shared.handle,
-            prefix: shared.prefix,
-            access: 'write',
-            appUid: null,
-            holder: env.users.other.username,
-            label: 'Trip',
-            createdAt: shared.createdAt,
-            revokedAt: null,
-            revokedBy: null,
-        });
-
-        const withMe = await req(
-            'GET',
-            '/kv/shares/with-me?limit=200',
-            env.users.other.token,
-        );
-        const withMeText = await withMe.text();
-        const withMePage = JSON.parse(withMeText) as {
-            items: Array<Record<string, unknown>>;
-        };
-        expect(
-            withMePage.items.find((row) => row.handle === shared.handle),
-        ).toEqual({
-            handle: shared.handle,
-            access: 'write',
-            appUid: null,
-            label: 'Trip',
-            createdAt: shared.createdAt,
-        });
-        expect(withMeText).not.toContain(env.users.user.username);
-        expect(withMeText).not.toContain(ownerUuid);
-        expect(withMeText).not.toContain(String(shared.prefix));
-    });
-
-    it('lets the holder unshare, and shows the owner they did', async () => {
-        const shared = await shareWithOther();
-        const removed = await req(
-            'DELETE',
-            `/kv/shares/${shared.handle}`,
-            env.users.other.token,
-        );
-        expect(removed.status).toBe(200);
-        await expect(removed.json()).resolves.toMatchObject({
-            handle: shared.handle,
-        });
-
-        const byMe = (await (
-            await req('GET', '/kv/shares?limit=200', env.users.user.token)
-        ).json()) as { items: Array<Record<string, unknown>> };
-        expect(
-            byMe.items.find((row) => row.handle === shared.handle),
-        ).toMatchObject({ revokedBy: 'holder' });
-    });
-
-    it('keeps the owner and prefix out of the holder`s grant audit after they unshare', async () => {
-        const shared = await shareWithOther({ access: 'write' });
-        const segment = String(shared.prefix).slice(0, -1);
-        const other = await env.server.stores.user.getByUsername(
-            env.users.other.username,
-        );
-        // A row an earlier build filed under the holder.
-        await env.server.stores.permission.auditUserUserPerm({
-            holder_user_id: other!.id,
-            issuer_user_id: other!.id,
-            permission: `kv-share-write:${ownerUuid}:os-global:${segment}`,
-            action: 'revoke',
-            reason: 'kv share handle unshared',
-        });
-        const removed = await req(
-            'DELETE',
-            `/kv/shares/${shared.handle}`,
-            env.users.other.token,
-        );
-        expect(removed.status).toBe(200);
-
-        // The revoke is filed under the owner, who granted it.
-        const auditOf = async (token: string) => {
-            const res = await req('GET', '/share/audit?limit=200', token);
-            expect(res.status).toBe(200);
-            return await res.text();
-        };
-        await vi.waitFor(async () => {
-            const owners = JSON.parse(await auditOf(env.users.user.token)) as {
-                items: Array<Record<string, unknown>>;
-            };
-            expect(owners.items).toContainEqual(
-                expect.objectContaining({
-                    action: 'revoke',
-                    issuer: env.users.user.username,
-                    holder: env.users.other.username,
-                    permission: expect.stringContaining(segment),
-                }),
-            );
-        });
-
-        const holders = await auditOf(env.users.other.token);
-        expect(holders).not.toContain(ownerUuid);
-        expect(holders).not.toContain(segment);
-    });
-
-    it('lets the owner revoke', async () => {
-        const shared = await shareWithOther();
-        const removed = await req(
-            'DELETE',
-            `/kv/shares/${shared.handle}`,
-            env.users.user.token,
-        );
-        expect(removed.status).toBe(200);
-    });
-
-    it('answers anyone else, and an unknown handle, with the same 404', async () => {
-        const shared = await shareWithOther();
-        const stranger = await createTestUser(env.server, {
-            username: `kvs-${uuidv4().slice(0, 8)}`,
-            password: 'pw-test-1234',
-        });
-        const strangers = await req(
-            'DELETE',
-            `/kv/shares/${shared.handle}`,
-            stranger.token,
-        );
-        const unknownHandle = `kvh-${uuidv4()}`;
-        const unknown = await req(
-            'DELETE',
-            `/kv/shares/${unknownHandle}`,
-            env.users.user.token,
-        );
-        expect(strangers.status).toBe(404);
-        expect(unknown.status).toBe(404);
-        const a = (await strangers.json()) as Record<string, unknown>;
-        const b = (await unknown.json()) as Record<string, unknown>;
-        expect(a.code).toBe(b.code);
-        expect(a.message).toBe(`No such handle: ${shared.handle}`);
-        expect(b.message).toBe(`No such handle: ${unknownHandle}`);
-    });
-
-    it('turns an anonymous caller away', async () => {
-        const res = await req('GET', '/kv/shares');
-        expect(res.status).toBeGreaterThanOrEqual(400);
-    });
-});
-
-describe('/events/kv-handles beside /kv/shares', () => {
-    let env: PuterTestEnv;
-
-    beforeAll(async () => {
-        env = await setupPuterTestEnv({
-            events: { enabled: true, kvHandles: true },
-            kv: { shareHandles: true },
-            unlimitedMetering: true,
-        } as IConfig);
-    }, BOOT_TIMEOUT_MS);
-
-    afterAll(async () => {
-        await env?.shutdown();
-    });
-
-    it('keeps its own request and response shapes, at watch by default', async () => {
-        const minted = await call(
-            env,
-            'POST',
-            '/events/kv-handles',
-            env.users.user.token,
-            {
-                granteeUsername: env.users.other.username,
-                prefix: 'alias-shape:',
-            },
-        );
-        expect(minted.status).toBe(200);
-        const body = (await minted.json()) as Record<string, unknown>;
-        expect(body).toEqual({ handle: body.handle, prefix: 'alias-shape:' });
-
-        const listed = (await (
-            await call(
-                env,
-                'GET',
-                '/events/kv-handles?limit=200',
-                env.users.user.token,
-            )
-        ).json()) as { items: Array<Record<string, unknown>> };
-        const row = listed.items.find((one) => one.handle === body.handle);
-        expect(row).toMatchObject({
-            prefix: 'alias-shape:',
-            appUid: 'os-global',
-            granteeUsername: env.users.other.username,
-            access: 'watch',
-            revokedBy: null,
-        });
-        expect(row).not.toHaveProperty('holder');
-
-        // The alias revoke stays the owner's: the holder is told it is absent.
-        const byHolder = await call(
-            env,
-            'DELETE',
-            `/events/kv-handles/${body.handle}`,
-            env.users.other.token,
-        );
-        expect(byHolder.status).toBe(404);
-    });
-
-    it('hands back a share it finds at the level it has, unless the body names one', async () => {
-        const shared = (await (
-            await call(env, 'POST', '/kv/shares', env.users.user.token, {
-                prefix: 'alias-keep:',
-                recipient: env.users.other.username,
-                access: 'write',
-            })
-        ).json()) as Record<string, unknown>;
-        const accessOf = async () => {
-            const listed = (await (
-                await call(
-                    env,
-                    'GET',
-                    '/kv/shares?limit=200',
-                    env.users.user.token,
-                )
-            ).json()) as { items: Array<Record<string, unknown>> };
-            return listed.items.find((one) => one.handle === shared.handle)
-                ?.access;
-        };
-        const mintAlias = (extra: Record<string, unknown> = {}) =>
-            call(env, 'POST', '/events/kv-handles', env.users.user.token, {
-                granteeUsername: env.users.other.username,
-                prefix: 'alias-keep:',
-                ...extra,
-            });
-
-        const again = await mintAlias();
-        expect(again.status).toBe(200);
-        await expect(again.json()).resolves.toEqual({
-            handle: shared.handle,
-            prefix: 'alias-keep:',
-        });
-        expect(await accessOf()).toBe('write');
-
-        expect((await mintAlias({ access: 'read' })).status).toBe(200);
-        expect(await accessOf()).toBe('read');
-    });
-});
-
-/**
- * Sharing asks for a confirmed email and nothing else. Booted with an SMS
- * provider configured, so a phone requirement would bite here if one were ever
- * added to these routes.
- */
-describe('verification on the mint routes', () => {
-    let env: PuterTestEnv;
-
-    beforeAll(async () => {
-        env = await setupPuterTestEnv({
-            events: { enabled: true, kvHandles: true },
-            kv: { shareHandles: true },
-            unlimitedMetering: true,
-            strict_email_verification_required: true,
-            prelude: { apiKey: 'test-key' },
-        } as IConfig);
-    }, BOOT_TIMEOUT_MS);
-
-    afterAll(async () => {
-        await env?.shutdown();
-    });
-
-    const makeUser = async (
-        patch: Record<string, unknown> = {},
-    ): Promise<TestUserCredentials> => {
-        const username = `kvv${uuidv4().slice(0, 8)}`;
-        const creds = await createTestUser(env.server, {
-            username,
-            password: 'pw-test-1234',
-        });
-        if (Object.keys(patch).length > 0) {
-            const row = await env.server.stores.user.getByUsername(username);
-            await env.server.stores.user.update(row!.id, patch);
-        }
-        return creds;
-    };
-
-    const mintBoth = (owner: TestUserCredentials, prefix: string) =>
-        Promise.all([
-            call(env, 'POST', '/kv/shares', owner.token, {
-                prefix: `${prefix}a:`,
-                recipient: env.users.other.username,
-            }),
-            call(env, 'POST', '/events/kv-handles', owner.token, {
-                prefix: `${prefix}b:`,
-                granteeUsername: env.users.other.username,
-            }),
-        ]);
-
-    it('refuses an account whose email is not confirmed, on both routes', async () => {
-        const owner = await makeUser();
-        for (const res of await mintBoth(owner, 'unconfirmed')) {
-            expect(res.status).toBe(403);
-            await expect(res.json()).resolves.toMatchObject({
-                code: 'account_is_not_verified',
-            });
-        }
-    });
-
-    it('lets a confirmed account share with no phone and no card', async () => {
-        const owner = await makeUser({
-            email: `kvv-${uuidv4().slice(0, 8)}@example.invalid`,
-            email_confirmed: 1,
-        });
-        for (const res of await mintBoth(owner, 'confirmed'))
-            expect(res.status).toBe(200);
-    });
-
-    it('never gates listing or unsharing', async () => {
-        const owner = await makeUser();
-        for (const path of ['/kv/shares', '/kv/shares/with-me'])
-            expect((await call(env, 'GET', path, owner.token)).status).toBe(
-                200,
-            );
-        const removed = await call(
-            env,
-            'DELETE',
-            `/kv/shares/kvh-${uuidv4()}`,
-            owner.token,
-        );
-        expect(removed.status).toBe(404);
-    });
-});

src/backend/controllers/kvShare/KvShareController.ts

@@ -1,172 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import type { Request, Response } from 'express';
-import type { Actor } from '../../core/actor.js';
-import { Controller, Delete, Get, Post } from '../../core/http/decorators.js';
-import { HttpError } from '../../core/http/HttpError.js';
-import { bodyRecord } from '../../core/http/requestBody.js';
-import { parseKvShareRecipient } from '../../services/kvShare/kvShares.js';
-import type { KvShareHandleListOptions } from '../../stores/events/KvShareHandleStore.js';
-import { KV_HANDLE_LIST_LIMIT_CAP } from '../../stores/events/KvShareHandleStore.js';
-import { KV_GLOBAL_APP_KEY } from '../../stores/systemKv/SystemKVStore.js';
-import { normalizeLimit } from '../../util/pagination.js';
-import { EVENTS_LIST_LIMIT } from '../events/limits.js';
-import { PuterController } from '../types.js';
-
-/** The app-less namespace is no app, so the wire says `null` for it. */
-const publicAppUid = (appUid: string): string | null =>
-    appUid === KV_GLOBAL_APP_KEY ? null : appUid;
-
-const pageOptions = (req: Request): KvShareHandleListOptions => {
-    const query = (req.query ?? {}) as Record<string, unknown>;
-    return {
-        limit: normalizeLimit(query.limit, { cap: KV_HANDLE_LIST_LIMIT_CAP }),
-        cursor: typeof query.cursor === 'string' ? query.cursor : undefined,
-        includeTotal: query.includeTotal === 'true',
-    };
-};
-
-/**
- * Sharing a region of one account's key-value data with another account.
- *
- * Gated like the events surface: `subdomain: 'api'` plus `allowAccessToken`,
- * with app-ness decided from `effectiveApp` in the service, which is where the
- * owner, holder, delegation and namespace rules live. Only sharing asks for a
- * confirmed email; listing, revoking and unsharing only narrow or report.
- */
-@Controller('/kv')
-export class KvShareController extends PuterController {
-    /**
-     * POST /kv/shares — share a region with another account, `read` unless the
-     * body asks otherwise. Sharing the same region with the same account again
-     * changes its level or label in place.
-     */
-    @Post('/shares', {
-        subdomain: 'api',
-        requireAuth: true,
-        allowAccessToken: true,
-        requireVerified: true,
-    })
-    async share(req: Request, res: Response): Promise<void> {
-        const actor = this.#requireActor(req);
-        const body = bodyRecord(req);
-        const share = await this.services.kvShare.mintKvHandle(
-            actor,
-            {
-                prefix: body.prefix,
-                recipient: parseKvShareRecipient(body.recipient),
-                access: body.access,
-                appUid: body.appUid,
-                label: body.label,
-            },
-            { defaultAccess: 'read' },
-        );
-        res.json({
-            handle: share.handle,
-            prefix: share.prefix,
-            access: share.access,
-            appUid: publicAppUid(share.appUid),
-            holder: share.holderUsername,
-            label: share.label,
-            createdAt: share.createdAt,
-        });
-    }
-
-    /** GET /kv/shares — what this account has shared out, retired included. */
-    @Get('/shares', {
-        subdomain: 'api',
-        requireAuth: true,
-        allowAccessToken: true,
-        rateLimit: EVENTS_LIST_LIMIT,
-    })
-    async listSharedByMe(req: Request, res: Response): Promise<void> {
-        const actor = this.#requireActor(req);
-        const page = await this.services.kvShare.listKvHandles(
-            actor,
-            pageOptions(req),
-        );
-        res.json({
-            items: page.items.map((row) => ({
-                handle: row.handle,
-                prefix: row.prefix,
-                access: row.access,
-                appUid: publicAppUid(row.appUid),
-                holder: row.holderUsername,
-                label: row.label,
-                createdAt: row.createdAt,
-                revokedAt: row.revokedAt,
-                revokedBy: row.revokedBy,
-            })),
-            ...(page.cursor ? { cursor: page.cursor } : {}),
-            ...(page.total !== undefined ? { total: page.total } : {}),
-        });
-    }
-
-    /** GET /kv/shares/with-me — live shares this account holds. */
-    @Get('/shares/with-me', {
-        subdomain: 'api',
-        requireAuth: true,
-        allowAccessToken: true,
-        rateLimit: EVENTS_LIST_LIMIT,
-    })
-    async listSharedWithMe(req: Request, res: Response): Promise<void> {
-        const actor = this.#requireActor(req);
-        const page = await this.services.kvShare.listKvSharesWithMe(
-            actor,
-            pageOptions(req),
-        );
-        res.json({
-            items: page.items.map((row) => ({
-                handle: row.handle,
-                access: row.access,
-                appUid: publicAppUid(row.appUid),
-                label: row.label,
-                createdAt: row.createdAt,
-            })),
-            ...(page.cursor ? { cursor: page.cursor } : {}),
-            ...(page.total !== undefined ? { total: page.total } : {}),
-        });
-    }
-
-    /**
-     * DELETE /kv/shares/:handle — the owner revokes, the holder gives it up,
-     * and anyone else is told it is not there.
-     */
-    @Delete('/shares/:handle', {
-        subdomain: 'api',
-        requireAuth: true,
-        allowAccessToken: true,
-    })
-    async unshare(req: Request, res: Response): Promise<void> {
-        const actor = this.#requireActor(req);
-        res.json(
-            await this.services.kvShare.removeKvShare(actor, req.params.handle),
-        );
-    }
-
-    #requireActor(req: Request): Actor {
-        const actor = req.actor;
-        if (!actor?.user)
-            throw new HttpError(401, 'Unauthorized', {
-                legacyCode: 'unauthorized',
-            });
-        return actor;
-    }
-}

src/backend/core/actor.test.ts

@@ -23,7 +23,6 @@ import {
     makeActor,
     SYSTEM_ACTOR,
     userRelatedActor,
-    viaWorkerOf,
     type Actor,
 } from './actor';
 
@@ -112,28 +111,3 @@ describe('assertResolvedActor', () => {
         );
     });
 });
-
-describe('viaWorkerOf', () => {
-    const user = { uuid: 'u-1', id: 1 };
-
-    it('reads a worker session or an events handler as server-side', () => {
-        expect(
-            viaWorkerOf(
-                makeActor({ user, session: { uid: 's-1', kind: 'worker' } }),
-            ),
-        ).toBe(true);
-        expect(viaWorkerOf(makeActor({ user, handlerDepth: 1 }))).toBe(true);
-    });
-
-    it('reads a browser session, an app or no actor at all as not', () => {
-        expect(
-            viaWorkerOf(
-                makeActor({ user, session: { uid: 's-1', kind: 'web' } }),
-            ),
-        ).toBe(false);
-        expect(viaWorkerOf(makeActor({ user, app: { uid: 'app-1' } }))).toBe(
-            false,
-        );
-        expect(viaWorkerOf(undefined)).toBe(false);
-    });
-});

src/backend/core/actor.ts

@@ -239,10 +239,3 @@ export const userRelatedActor = (actor: Actor): Actor => {
 /** How many events handler runs led to a write by this actor. */
 export const handlerDepthOf = (actor: Actor | undefined | null): number =>
     actor?.handlerDepth ?? 0;
-
-/**
- * Whether a write by this actor was made by server-side code running as the
- * account: a worker session, or an events handler.
- */
-export const viaWorkerOf = (actor: Actor | undefined | null): boolean =>
-    actor?.session?.kind === 'worker' || handlerDepthOf(actor) > 0;

src/backend/core/http/middleware/privateAppGate.test.ts

@@ -950,8 +950,7 @@ describe('resolvePrivateIdentity', () => {
         expect(out.userUid).toBeUndefined();
     });
 
-    it('ignores an app-issued access token even for the target app', async () => {
-        // A scoped token (e.g. a read URL) is not the account, whoever issued it.
+    it('accepts an app-issued access token minted for the target app', async () => {
         const user = await makeUser();
         const targetUid = `app-target-${uuidv4()}`;
         const issuer = makeActor({
@@ -971,11 +970,11 @@ describe('resolvePrivateIdentity', () => {
             sessionCookieName: 'puter_auth_token',
             expectedAppUid: targetUid,
         });
-        expect(out.source).toBe('none');
-        expect(out.userUid).toBeUndefined();
+        expect(out.source).toBe('session-cookie');
+        expect(out.userUid).toBe(user.uuid);
     });
 
-    it('ignores a user-issued scoped access token', async () => {
+    it('still accepts a user-issued access token, which is portable', async () => {
         const user = await makeUser();
         const issuer = makeActor({ user: { uuid: user.uuid } });
         const out = await resolvePrivateIdentity({
@@ -984,46 +983,7 @@ describe('resolvePrivateIdentity', () => {
                 actor: makeActor({
                     user: { uuid: user.uuid },
                     accessToken: { uid: `tok-${uuidv4()}`, issuer },
-                }),
-            }),
-            authService,
-            sessionCookieName: 'puter_auth_token',
-            expectedAppUid: `app-target-${uuidv4()}`,
-        });
-        expect(out.source).toBe('none');
-        expect(out.userUid).toBeUndefined();
-    });
-
-    it('ignores a scoped access token when the host has no app', async () => {
-        const user = await makeUser();
-        const issuer = makeActor({ user: { uuid: user.uuid } });
-        const out = await resolvePrivateIdentity({
-            req: reqOf({
-                cookies: {},
-                actor: makeActor({
-                    user: { uuid: user.uuid },
-                    accessToken: { uid: `tok-${uuidv4()}`, issuer },
-                }),
-            }),
-            authService,
-            sessionCookieName: 'puter_auth_token',
-        });
-        expect(out.source).toBe('none');
-    });
-
-    it('accepts a full-access token, which holds the account', async () => {
-        const user = await makeUser();
-        const issuer = makeActor({ user: { uuid: user.uuid } });
-        const out = await resolvePrivateIdentity({
-            req: reqOf({
-                cookies: {},
-                actor: makeActor({
-                    user: { uuid: user.uuid },
-                    accessToken: {
-                        uid: `tok-${uuidv4()}`,
-                        issuer,
-                        fullAccess: true,
-                    },
+                    session: { uid: 'sess-1' },
                 }),
             }),
             authService,

src/backend/core/http/middleware/privateAppGate.ts

@@ -25,7 +25,7 @@ import {
 } from '../../../services/auth/AuthService';
 import type { AppStore } from '../../../stores/app/AppStore.js';
 import type { IConfig } from '../../../types';
-import { isAccessTokenActor, isAccountContext, type Actor } from '../../actor';
+import type { Actor } from '../../actor';
 
 /**
  * Support helpers for the private-app access gate — ported from v1's
@@ -460,15 +460,11 @@ export async function resolvePrivateIdentity(opts: {
  * "No app anywhere in the chain" is the portable case, so read `effectiveApp` —
  * an app-issued access token has no `app` of its own and would otherwise pass
  * as a plain session on any private host.
- *
- * A scoped access token (a read URL, whoever issued it) is never the account
- * here: the hosted cookie minted from it would outlive the token's revocation.
  */
 function actorMatchesExpectedApp(
     actor: Actor,
     expectedAppUid: string | undefined,
 ): boolean {
-    if (isAccessTokenActor(actor) && !isAccountContext(actor)) return false;
     if (!expectedAppUid) return true;
     const app = actor.effectiveApp;
     if (!app) return true;

src/backend/drivers/kv/KVStoreDriver.test.ts

@@ -14,10 +14,7 @@ import {
     APP_DATA_KV_METHOD_OPS,
     appDataPermission,
 } from '../../services/permission/appDataScopes.ts';
-import { kvNamespace } from '../../stores/systemKv/SystemKVStore.ts';
 import { createTestUser, setupTestServer } from '../../testUtil.ts';
-import type { IConfig } from '../../types.ts';
-import { sealCursor, unsealCursor } from '../../util/pagination.ts';
 import { KV_COSTS } from './costs.ts';
 import type { KVStoreDriver } from './KVStoreDriver.ts';
 import {
@@ -1555,301 +1552,6 @@ describe('KVStoreDriver', () => {
             expect(own).toContain('token');
         });
 
-        // -- Cross-app cursors ----------------------------------------------
-
-        const secret = () =>
-            (target as unknown as { config: IConfig }).config.jwt_secret_v2;
-
-        /** A cursor as the server reads it, its key decoded, or null. */
-        const opened = (cursor: string) => {
-            const payload = unsealCursor(cursor, secret());
-            return payload
-                ? {
-                      ...payload,
-                      k: Buffer.from(String(payload.k), 'base64url').toString(
-                          'utf8',
-                      ),
-                  }
-                : null;
-        };
-
-        /** Everything a cursor shows to the server and to a base64 decoder. */
-        const revealed = (cursor: string) =>
-            [
-                JSON.stringify(opened(cursor)),
-                Buffer.from(cursor, 'base64').toString('utf8'),
-                Buffer.from(cursor, 'base64url').toString('utf8'),
-            ].join('\n');
-
-        const encode = (payload: unknown) =>
-            Buffer.from(JSON.stringify(payload)).toString('base64');
-
-        type Page = { items: string[]; cursor?: string; total?: number };
-
-        const writeAs = (
-            actorForCall: Actor,
-            key: string,
-            disableSharing = false,
-        ) =>
-            inCtx(
-                () =>
-                    target.set({
-                        key,
-                        value: key,
-                        ...(disableSharing
-                            ? { optConfig: { disableSharing: true } }
-                            : {}),
-                    }),
-                actorForCall,
-            );
-
-        it('resumes a cross-app page after a private entry it skipped, padding every cursor to one length', async () => {
-            const { owner, calendar, contacts, calendarActor, contactsActor } =
-                await setup();
-            await writeAs(contactsActor, 'a-hidden-oauth-token-name', true);
-            await writeAs(contactsActor, 'b');
-            await writeAs(contactsActor, 'c-a-much-longer-public-key-name');
-            await grant(owner, calendar.uid, appDataPermission(contacts.uid));
-            const page = (cursor?: string) =>
-                crossApp(calendarActor, contacts.uid, (optConfig) =>
-                    target.list({
-                        as: 'keys',
-                        limit: 1,
-                        ...(cursor ? { cursor } : {}),
-                        optConfig,
-                    }),
-                ) as Promise<Page>;
-
-            // The scan's first row is the private one.
-            const first = await page();
-            expect(first.items).toEqual(['b']);
-            expect(revealed(first.cursor!)).not.toContain('hidden-oauth');
-            expect(opened(first.cursor!)?.k).toBe('b');
-
-            const second = await page(first.cursor);
-            expect(second.items).toEqual(['c-a-much-longer-public-key-name']);
-            expect(second.cursor!.length).toBe(first.cursor!.length);
-        });
-
-        // Over a thousand writes and reads: slow when the whole suite runs.
-        it('pads a cursor left on a long run of private entries to the same length', async () => {
-            const { owner, calendar, contacts, calendarActor, contactsActor } =
-                await setup();
-            // More than one call reads past, so the page ends on a hidden row.
-            const hidden = Array.from(
-                { length: 1100 },
-                (_, i) => `h-hidden-${String(i).padStart(4, '0')}`,
-            );
-            for (let at = 0; at < hidden.length; at += 1000)
-                await inCtx(
-                    () =>
-                        target.batchPut({
-                            items: hidden
-                                .slice(at, at + 1000)
-                                .map((key) => ({ key, value: 1 })),
-                            optConfig: { disableSharing: true },
-                        }),
-                    contactsActor,
-                );
-            await writeAs(contactsActor, 'z');
-            await grant(owner, calendar.uid, appDataPermission(contacts.uid));
-
-            const keys: string[] = [];
-            const cursors: string[] = [];
-            let emptyPages = 0;
-            let cursor: string | undefined;
-            for (let pages = 0; pages < 10; pages++) {
-                const page = (await crossApp(
-                    calendarActor,
-                    contacts.uid,
-                    (optConfig) =>
-                        target.list({
-                            as: 'keys',
-                            limit: 1,
-                            ...(cursor ? { cursor } : {}),
-                            optConfig,
-                        }),
-                )) as Page;
-                keys.push(...page.items);
-                if (page.items.length === 0) emptyPages++;
-                cursor = page.cursor;
-                if (!cursor) break;
-                cursors.push(cursor);
-                expect(
-                    Buffer.from(cursor, 'base64').toString('utf8'),
-                ).not.toContain('h-hidden');
-            }
-            expect(keys).toEqual(['entry', 'z']);
-            expect(emptyPages).toBeGreaterThan(0);
-            expect(new Set(cursors.map((c) => c.length)).size).toBe(1);
-        }, 30_000);
-
-        describe('paging a namespace with private entries in it', () => {
-            // Lengths differ, so an unpadded cursor would show which it is.
-            const PUBLIC = [
-                'entry',
-                'k1',
-                'k3-longer',
-                'k4',
-                'k6-longest-of-all',
-            ];
-            const PRIVATE = ['k2', 'k5', 'k7', 'k8'];
-
-            const seeded = async () => {
-                const fixture = await setup();
-                for (const key of PUBLIC.slice(1))
-                    await writeAs(fixture.contactsActor, key);
-                for (const key of PRIVATE)
-                    await writeAs(fixture.contactsActor, key, true);
-                await grant(
-                    fixture.owner,
-                    fixture.calendar.uid,
-                    appDataPermission(fixture.contacts.uid),
-                );
-                return fixture;
-            };
-
-            it.each(
-                [false, true].flatMap((reverse) =>
-                    [false, true].map((includeTotal) => ({
-                        reverse,
-                        includeTotal,
-                    })),
-                ),
-            )(
-                'returns every public entry once, reverse $reverse, includeTotal $includeTotal',
-                async ({ reverse, includeTotal }) => {
-                    const { contacts, calendarActor } = await seeded();
-                    const keys: string[] = [];
-                    const lengths = new Set<number>();
-                    let cursor: string | undefined;
-                    let pages = 0;
-                    do {
-                        const page = (await crossApp(
-                            calendarActor,
-                            contacts.uid,
-                            (optConfig) =>
-                                target.list({
-                                    as: 'keys',
-                                    limit: 2,
-                                    ...(reverse ? { reverse } : {}),
-                                    ...(includeTotal ? { includeTotal } : {}),
-                                    ...(cursor ? { cursor } : {}),
-                                    optConfig,
-                                }),
-                        )) as Page;
-                        keys.push(...page.items);
-                        if (includeTotal)
-                            expect(page.total).toBe(PUBLIC.length);
-                        cursor = page.cursor;
-                        if (cursor) {
-                            lengths.add(cursor.length);
-                            const position = opened(cursor);
-                            expect(position).not.toBeNull();
-                            expect(PRIVATE).not.toContain(position!.k);
-                        }
-                        pages++;
-                    } while (cursor && pages < 10);
-
-                    expect(keys).toEqual(
-                        reverse ? [...PUBLIC].reverse() : PUBLIC,
-                    );
-                    expect(lengths.size).toBe(1);
-                },
-            );
-
-            it('still reads a plain cursor from before they were sealed, and seals the next one', async () => {
-                const { owner, contacts, calendarActor } = await seeded();
-                const namespace = kvNamespace(owner.user.uuid!, contacts.uid);
-                const list = (cursor: unknown, limit = 10) =>
-                    crossApp(calendarActor, contacts.uid, (optConfig) =>
-                        target.list({ as: 'keys', limit, cursor, optConfig }),
-                    ) as Promise<Page>;
-
-                expect(
-                    (await list(encode({ namespace, key: 'k1' }))).items,
-                ).toEqual(PUBLIC.slice(2));
-                expect(
-                    (
-                        await list(
-                            encode({
-                                reverse: true,
-                                key: { namespace, key: 'k4' },
-                            }),
-                        )
-                    ).items,
-                ).toEqual(PUBLIC.slice(0, 3).reverse());
-
-                const next = await list(encode({ namespace, key: 'k1' }), 1);
-                expect(next.items).toEqual(['k3-longer']);
-                expect(opened(next.cursor!)).toMatchObject({ k: 'k3-longer' });
-            });
-
-            it('refuses a plain or sealed cursor for another namespace', async () => {
-                const { owner, calendar, contacts, calendarActor } =
-                    await seeded();
-                const other = await makeRealApp(owner.user.id!);
-                await writeAs(asApp(owner, other), 'k1');
-                await writeAs(asApp(owner, other), 'k2');
-                await grant(owner, calendar.uid, appDataPermission(other.uid));
-                const fromOther = (
-                    (await crossApp(calendarActor, other.uid, (optConfig) =>
-                        target.list({ as: 'keys', limit: 1, optConfig }),
-                    )) as Page
-                ).cursor!;
-                await writeAs(calendarActor, 'own-1');
-                await writeAs(calendarActor, 'own-2');
-                const ownCursor = (
-                    (await inCtx(
-                        () => target.list({ as: 'keys', limit: 1 }),
-                        calendarActor,
-                    )) as Page
-                ).cursor!;
-                const elsewhere = kvNamespace(owner.user.uuid!, other.uid);
-                const stranger = kvNamespace('someone-else', contacts.uid);
-
-                const forged: unknown[] = [
-                    fromOther,
-                    encode({ namespace: elsewhere, key: 'k1' }),
-                    encode({ namespace: stranger, key: 'k1' }),
-                    { namespace: elsewhere, key: 'k1' },
-                    encode({
-                        reverse: true,
-                        key: { namespace: elsewhere, key: 'k1' },
-                    }),
-                    encode({
-                        namespace: kvNamespace(owner.user.uuid!, contacts.uid),
-                        key: 'k1',
-                        extra: true,
-                    }),
-                    sealCursor({ id: 1 }, secret()),
-                    sealCursor(
-                        {
-                            s: elsewhere,
-                            k: Buffer.from('k1').toString('base64url'),
-                        },
-                        secret(),
-                    ),
-                    ownCursor,
-                ];
-                for (const cursor of forged)
-                    await expect(
-                        crossApp(calendarActor, contacts.uid, (optConfig) =>
-                            target.list({
-                                as: 'keys',
-                                limit: 1,
-                                cursor,
-                                optConfig,
-                            }),
-                        ),
-                        JSON.stringify(cursor),
-                    ).rejects.toMatchObject({
-                        statusCode: 400,
-                        message: 'invalid kv: cursor',
-                    });
-            });
-        });
-
         it('refuses cross-app writes and deletes against a private entry', async () => {
             const { owner, calendar, contacts, calendarActor, contactsActor } =
                 await setup();

src/backend/drivers/kv/KVStoreDriver.ts

@@ -32,29 +32,9 @@ import {
     appDataPermission,
     appDataSharingAllowed,
 } from '../../services/permission/appDataScopes.js';
-import {
-    KV_GLOBAL_APP_KEY,
-    KV_MAX_KEY_BYTES,
-    kvNamespace,
-    type KVOpts,
-    type KVUsage,
-} from '../../stores/systemKv/SystemKVStore.js';
-import { KV_SHARE_HANDLE_WIDTHS } from '../../stores/events/columnWidths.js';
+import type { KVOpts, KVUsage } from '../../stores/systemKv/SystemKVStore.js';
 import { assertActorHasCredits } from '../../services/metering/enforcement.js';
-import { isKvHandleId } from '../../services/events/subjects.js';
-import {
-    KV_HANDLE_KEY_MAX_BYTES,
-    KV_SHARE_PREFIX_MAX_BYTES,
-    kvHandlesDisabled,
-    kvShareLevelForMethod,
-    kvSharePermission,
-} from '../../services/kvShare/kvShares.js';
-import {
-    decodeCursor,
-    normalizeLimit,
-    sealCursor,
-    unsealCursor,
-} from '../../util/pagination.js';
+import { normalizeLimit } from '../../util/pagination.js';
 import { KV_COSTS } from './costs.js';
 import {
     KV_MAX_BATCH_PUT_ITEMS,
@@ -62,143 +42,16 @@ import {
     KV_MAX_LIST_LIMIT,
 } from './limits.js';
 
-/** `optConfig` as every KV method takes it. */
-interface KvOptConfig {
-    /** Another app's namespace, which the user let this app reach. */
-    appUuid?: string;
-    /** Writes the entry private to the app that wrote it. */
-    disableSharing?: boolean;
-    /**
-     * A share handle: the call reaches that region of its owner's data, with
-     * keys relative to it.
-     */
-    handle?: string;
-    /** `set` only: write only when no live entry holds the key. */
-    onlyIfAbsent?: boolean;
-}
-
 /**
  * Every KV method's argument object, as far as option resolution cares: the
  * namespace override, plus the expiry parameters that can delete an entry.
  */
 type KvCallArgs = {
-    optConfig?: KvOptConfig;
+    optConfig?: { appUuid?: string; disableSharing?: boolean };
     expireAt?: unknown;
     ttl?: unknown;
 };
 
-/**
- * Store options plus, for a call through a share handle, the handle and its
- * region's prefix: keys go in under it and come back out relative to it.
- */
-type DriverKvOpts = KVOpts & { handle?: string; handlePrefix?: string };
-
-type KvListResult =
-    | unknown[]
-    | { items: unknown[]; cursor?: string; total?: number };
-
-/**
- * A listing of another namespace, cross-app or through a handle: what its
- * cursors are sealed to, the namespace a position rebuilds in, and the prefix
- * its keys are relative to.
- */
-interface ForeignListing {
-    bind: string;
-    namespace: string;
-    prefix: string;
-    /** Cross-app cursors were plain before they were sealed. */
-    acceptsPlain: boolean;
-}
-
-/**
- * Plaintext bytes a foreign listing's cursor is padded to: a key at the store's
- * limit in base64url, plus room for the binding and the envelope.
- */
-const FOREIGN_CURSOR_BYTES = Math.ceil((KV_MAX_KEY_BYTES * 4) / 3) + 256;
-
-/** Whether `value` is a store position, `{ namespace, key }`, in `namespace`. */
-const isPositionIn = (value: unknown, namespace: string): boolean => {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return false;
-    const { namespace: named, key, ...rest } = value as Record<string, unknown>;
-    return (
-        named === namespace &&
-        typeof key === 'string' &&
-        Object.keys(rest).length === 0
-    );
-};
-
-// -- Share-handle errors ----------------------------------------------
-
-/**
- * Unknown, retired, not the caller's, owner gone or suspended, or namespace app
- * deleted: one body for all of them, so no call can tell them apart.
- */
-const handleNotFound = (): HttpError =>
-    new HttpError(404, 'kv: no such share handle', {
-        legacyCode: 'kv_handle_not_found',
-    });
-
-/** Only ever told to the handle's holder. */
-const handleAccessDenied = (): HttpError =>
-    new HttpError(403, 'kv: this share handle does not allow this call', {
-        legacyCode: 'kv_handle_access_denied',
-    });
-
-const handleOptionInvalid = (message: string): HttpError =>
-    new HttpError(400, message, { legacyCode: 'kv_handle_option_invalid' });
-
-const handleKeyInvalid = (): HttpError =>
-    new HttpError(
-        400,
-        `kv: a key used with a share handle must be a non-empty string of at most ${KV_HANDLE_KEY_MAX_BYTES} bytes`,
-        { legacyCode: 'kv_handle_key_invalid' },
-    );
-
-/** The key limit, so no pattern length can tell how long the prefix is. */
-const handlePatternInvalid = (): HttpError =>
-    new HttpError(
-        400,
-        `kv: a pattern used with a share handle may be at most ${KV_HANDLE_KEY_MAX_BYTES} bytes`,
-        { legacyCode: 'kv_handle_key_invalid' },
-    );
-
-const invalidCursor = (): HttpError =>
-    new HttpError(400, 'invalid kv: cursor', { legacyCode: 'bad_request' });
-
-/** A stored key outside the handle's region, which a scan can't return. */
-const outsideRegion = (): HttpError =>
-    new HttpError(500, 'kv: internal error', { legacyCode: 'internal_error' });
-
-const viaHandle = (args?: KvCallArgs): boolean =>
-    args?.optConfig?.handle !== undefined && args.optConfig.handle !== null;
-
-/** `onlyIfAbsent` as a boolean, refusing anything else a raw body sends. */
-const parseOnlyIfAbsent = (value: unknown): boolean => {
-    if (value === undefined || value === null || value === false) return false;
-    if (value === true) return true;
-    throw new HttpError(400, 'kv: onlyIfAbsent must be a boolean', {
-        legacyCode: 'bad_request',
-    });
-};
-
-/**
- * A store error with every stored key it names put back the way the caller
- * named it, so the handle's prefix never leaves in a message.
- */
-const relativizeError = (
-    err: unknown,
-    prefix: string,
-    keys: readonly string[],
-): unknown => {
-    if (!(err instanceof Error) || typeof err.message !== 'string') return err;
-    let message = err.message;
-    for (const key of keys)
-        message = message.split(`${prefix}${key}`).join(key);
-    if (message !== err.message) err.message = message;
-    return err;
-};
-
 /**
  * Methods that stay available to an account with nothing left of its budget.
  * Each one only ever reduces what the account is storing, and turning those
@@ -288,25 +141,13 @@ export class KVStoreDriver extends PuterDriver {
         }));
     }
 
-    /**
-     * A key as the caller sent it. Through a handle it is relative to the
-     * region, and held to the handle's own fixed limit.
-     */
-    #coerceKey(key: unknown, args?: KvCallArgs): string {
+    #coerceKey(key: unknown): string {
         if (key === null || key === undefined) {
             throw new HttpError(400, 'Missing `key`', {
                 legacyCode: 'bad_request',
             }); // legacyCode for backward compatibility with old error handling in controllers
         }
         const str = typeof key === 'string' ? key : String(key);
-        if (viaHandle(args)) {
-            if (
-                str === '' ||
-                Buffer.byteLength(str, 'utf8') > KV_HANDLE_KEY_MAX_BYTES
-            )
-                throw handleKeyInvalid();
-            return str;
-        }
         if (str === '')
             throw new HttpError(400, 'Missing `key`', {
                 legacyCode: 'bad_request',
@@ -314,38 +155,7 @@ export class KVStoreDriver extends PuterDriver {
         return str;
     }
 
-    /** The key as stored: through a handle, placed under its prefix. */
-    #storeKey(key: string, opts: DriverKvOpts): string {
-        return opts.handlePrefix === undefined
-            ? key
-            : `${opts.handlePrefix}${key}`;
-    }
-
-    /** A stored key as a handle's caller names it; fails closed outside it. */
-    #relativeKey(key: unknown, prefix: string): string {
-        if (typeof key !== 'string' || !key.startsWith(prefix))
-            throw outsideRegion();
-        return key.slice(prefix.length);
-    }
-
-    /**
-     * Run one store call. Through a handle, an error naming a stored key names
-     * the caller's relative key instead.
-     */
-    async #inRegion<T>(
-        opts: DriverKvOpts,
-        keys: readonly string[],
-        call: () => Promise<T>,
-    ): Promise<T> {
-        if (opts.handlePrefix === undefined) return call();
-        try {
-            return await call();
-        } catch (err) {
-            throw relativizeError(err, opts.handlePrefix, keys);
-        }
-    }
-
-    async #opts(method: string, args: KvCallArgs): Promise<DriverKvOpts> {
+    async #opts(method: string, args: KvCallArgs): Promise<KVOpts> {
         const actor = Context.get('actor') as Actor | undefined;
 
         // Every method resolves its options here first, so this is the one
@@ -360,8 +170,6 @@ export class KVStoreDriver extends PuterDriver {
             );
         }
 
-        if (viaHandle(args)) return this.#handleOpts(actor, method, args);
-
         const appUuid = args.optConfig?.appUuid;
         // Through the issuer chain, not `actor.app`: an access-token actor
         // carries no app of its own, so keying off `app` would read a token an
@@ -390,214 +198,6 @@ export class KVStoreDriver extends PuterDriver {
         return { actor, namespaceAppUuid: appUuid };
     }
 
-    /**
-     * A call through a share handle, resolved to the owner's namespace. The
-     * handle row only names the region and whose it is; the grant, checked here
-     * on every call, is the authority. One check covers every key of the call,
-     * since they all sit under the handle's prefix.
-     */
-    async #handleOpts(
-        actor: Actor | undefined,
-        method: string,
-        args: KvCallArgs,
-    ): Promise<DriverKvOpts> {
-        if (this.config.kv?.shareHandles !== true) throw kvHandlesDisabled();
-
-        const optConfig = args.optConfig ?? {};
-        const level = kvShareLevelForMethod(method);
-        if (optConfig.appUuid || optConfig.disableSharing)
-            throw handleOptionInvalid(
-                'kv: `handle` cannot be combined with `appUuid` or `disableSharing`',
-            );
-        if (level === null)
-            throw handleOptionInvalid(
-                `kv: \`${method}\` is not available through a share handle`,
-            );
-
-        const handle: unknown = optConfig.handle;
-        if (typeof handle !== 'string')
-            throw handleOptionInvalid('kv: `handle` must be a string');
-        const userId = actor?.user?.id;
-        if (
-            !actor ||
-            typeof userId !== 'number' ||
-            handle.length > KV_SHARE_HANDLE_WIDTHS.handle.max ||
-            !isKvHandleId(handle)
-        )
-            throw handleNotFound();
-
-        const live = await this.stores.kvShareHandle.getLive(handle);
-        if (!live || live.ownerSuspended) throw handleNotFound();
-        const { row, ownerUuid } = live;
-        // Bound to its grantee: a handle id is an address, not a bearer
-        // credential, so another holder's overlapping grant doesn't reach it.
-        if (userId !== row.granteeUserId && userId !== row.ownerUserId)
-            throw handleNotFound();
-
-        // Side by side, so the app lookup costs no round trip of its own.
-        const [appGone, allowed] = await Promise.all([
-            row.appUid === KV_GLOBAL_APP_KEY
-                ? false
-                : this.stores.app.getByUid(row.appUid).then((app) => !app),
-            this.services.permission.check(
-                actor,
-                kvSharePermission(ownerUuid, row.appUid, row.keyPrefix, level),
-            ),
-        ]);
-        if (appGone) throw handleNotFound();
-        if (!allowed) {
-            // Asked only on the way out: whoever can still watch the region
-            // is its holder, and only they may learn the level is too low.
-            const holds = await this.services.permission.check(
-                actor,
-                kvSharePermission(
-                    ownerUuid,
-                    row.appUid,
-                    row.keyPrefix,
-                    'watch',
-                ),
-            );
-            throw holds ? handleAccessDenied() : handleNotFound();
-        }
-        // Past the cap only a watch handle can be, reached through a wider
-        // grant; the fixed key limit holders are shown assumes the cap.
-        if (
-            Buffer.byteLength(row.keyPrefix, 'utf8') > KV_SHARE_PREFIX_MAX_BYTES
-        )
-            throw handleAccessDenied();
-
-        return {
-            actor,
-            namespaceUser: { uuid: ownerUuid, id: row.ownerUserId },
-            namespaceAppUuid: row.appUid,
-            handle,
-            handlePrefix: row.keyPrefix,
-        };
-    }
-
-    /** Set when a listing covers another namespace, cross-app or by handle. */
-    #foreignListing(opts: DriverKvOpts): ForeignListing | undefined {
-        if (opts.handle !== undefined)
-            return {
-                bind: opts.handle,
-                namespace: kvNamespace(
-                    opts.namespaceUser!.uuid,
-                    opts.namespaceAppUuid!,
-                ),
-                prefix: opts.handlePrefix!,
-                acceptsPlain: false,
-            };
-        if (!opts.namespaceAppUuid) return undefined;
-        const namespace = kvNamespace(
-            opts.actor!.user.uuid!,
-            opts.namespaceAppUuid,
-        );
-        return { bind: namespace, namespace, prefix: '', acceptsPlain: true };
-    }
-
-    /**
-     * A foreign listing's cursor as a store position, rebuilt in the listing's
-     * own namespace and region. Only a cursor sealed to this listing opens, or
-     * a plain cross-app one naming the same namespace.
-     */
-    #cursorIn(
-        cursor: unknown,
-        listing: ForeignListing,
-    ): Record<string, unknown> | undefined {
-        if (cursor === undefined || cursor === null) return undefined;
-        if (typeof cursor === 'string') {
-            if (cursor.trim() === '') return undefined;
-            const sealed = unsealCursor(
-                cursor.trim(),
-                this.config.jwt_secret_v2,
-            );
-            if (sealed) {
-                const { s, k, r, ...rest } = sealed;
-                if (
-                    s !== listing.bind ||
-                    typeof k !== 'string' ||
-                    (r !== undefined && r !== true) ||
-                    Object.keys(rest).length > 0
-                )
-                    throw invalidCursor();
-                const position = {
-                    namespace: listing.namespace,
-                    key: `${listing.prefix}${Buffer.from(k, 'base64url').toString('utf8')}`,
-                };
-                return r ? { reverse: true, key: position } : position;
-            }
-        } else if (typeof cursor !== 'object') throw invalidCursor();
-        if (!listing.acceptsPlain) throw invalidCursor();
-
-        const plain = decodeCursor(
-            cursor as string | Record<string, unknown>,
-            'kv: cursor',
-        );
-        if (plain === undefined || isPositionIn(plain, listing.namespace))
-            return plain;
-        const { reverse, key, ...rest } = plain;
-        if (
-            reverse === true &&
-            Object.keys(rest).length === 0 &&
-            isPositionIn(key, listing.namespace)
-        )
-            return plain;
-        throw invalidCursor();
-    }
-
-    /**
-     * The store's next-page position, sealed to the listing and padded to one
-     * length, with its key relative to the region.
-     */
-    #cursorOut(cursor: string, listing: ForeignListing): string | undefined {
-        const decoded = decodeCursor(cursor);
-        const reverse = decoded?.reverse === true;
-        const position = (reverse ? decoded?.key : decoded) as
-            | { namespace?: unknown; key?: unknown }
-            | undefined;
-        if (position?.namespace !== listing.namespace) throw outsideRegion();
-        const key = this.#relativeKey(position.key, listing.prefix);
-        return sealCursor(
-            {
-                s: listing.bind,
-                k: Buffer.from(key, 'utf8').toString('base64url'),
-                ...(reverse ? { r: true } : {}),
-            },
-            this.config.jwt_secret_v2,
-            { padTo: FOREIGN_CURSOR_BYTES },
-        );
-    }
-
-    /** A foreign listing as its caller sees it: keys relative, cursor sealed. */
-    #foreignResult(
-        res: KvListResult,
-        as: string | undefined,
-        listing: ForeignListing,
-    ): KvListResult {
-        const { prefix } = listing;
-        const relative = (items: unknown[]): unknown[] => {
-            if (as === 'values' || prefix === '') return items;
-            if (as === 'keys')
-                return items.map((key) => this.#relativeKey(key, prefix));
-            return items.map((entry) => {
-                const { key, value } = entry as {
-                    key: unknown;
-                    value: unknown;
-                };
-                return { key: this.#relativeKey(key, prefix), value };
-            });
-        };
-        if (Array.isArray(res)) return relative(res);
-        const cursor = res.cursor
-            ? this.#cursorOut(res.cursor, listing)
-            : undefined;
-        return {
-            items: relative(res.items),
-            ...(cursor ? { cursor } : {}),
-            ...(res.total !== undefined ? { total: res.total } : {}),
-        };
-    }
-
     async #assertCrossAppKvAccess(
         actor: Actor,
         targetAppUid: string,
@@ -722,7 +322,7 @@ export class KVStoreDriver extends PuterDriver {
 
     async get(args: {
         key: unknown;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
         const { key } = args;
         if (key === undefined || key === null) {
@@ -743,55 +343,45 @@ export class KVStoreDriver extends PuterDriver {
 
         if (Array.isArray(key)) {
             if (key.length === 0) return [];
-            const coerced = key.map((k) => this.#coerceKey(k, args));
-            const { res, usage } = await this.#inRegion(opts, coerced, () =>
-                this.stores.kv.get(
-                    { key: coerced.map((k) => this.#storeKey(k, opts)) },
-                    opts,
-                ),
+            const coerced = key.map((k) => this.#coerceKey(k));
+            const { res, usage } = await this.stores.kv.get(
+                { key: coerced },
+                opts,
             );
             this.#meter(opts.actor, usage);
             return res;
         }
 
-        const coerced = this.#coerceKey(key, args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.get({ key: this.#storeKey(coerced, opts) }, opts),
+        const { res, usage } = await this.stores.kv.get(
+            { key: this.#coerceKey(key) },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
     }
 
-    /**
-     * `false` only for an `onlyIfAbsent` write that found a live entry, which
-     * is left as it was.
-     */
     async set(args: {
         key: unknown;
         value: unknown;
         expireAt?: number | null;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string; disableSharing?: boolean };
     }): Promise<boolean> {
         const { key, value, expireAt } = args;
-        const coerced = this.#coerceKey(key, args);
+        const coerced = this.#coerceKey(key);
         if (value === undefined)
             throw new HttpError(400, 'Missing `value`', {
                 legacyCode: 'bad_request',
             }); // legacyCode for backward compatibility with old error handling in controllers
-        const onlyIfAbsent = parseOnlyIfAbsent(args.optConfig?.onlyIfAbsent);
 
         const opts = await this.#opts('set', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.set(
-                {
-                    key: this.#storeKey(coerced, opts),
-                    value,
-                    expireAt,
-                    disableSharing: args.optConfig?.disableSharing,
-                    onlyIfAbsent,
-                },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.set(
+            {
+                key: coerced,
+                value,
+                expireAt,
+                disableSharing: args.optConfig?.disableSharing,
+            },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -799,7 +389,7 @@ export class KVStoreDriver extends PuterDriver {
 
     async batchPut(args: {
         items: Array<{ key: string; value: unknown; expireAt?: number | null }>;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string; disableSharing?: boolean };
     }): Promise<boolean> {
         const { items } = args;
         if (!Array.isArray(items) || items.length === 0) {
@@ -814,27 +404,17 @@ export class KVStoreDriver extends PuterDriver {
                 { legacyCode: 'bad_request' },
             );
         }
-        // A batch write takes no condition, so it can't promise this per item.
-        if (parseOnlyIfAbsent(args.optConfig?.onlyIfAbsent)) {
-            throw new HttpError(
-                400,
-                'kv: onlyIfAbsent is not available on a batch write',
-                { legacyCode: 'invalid_request' },
-            );
-        }
 
         const coerced = items.map((item) => ({
-            key: this.#coerceKey(item.key, args),
+            key: this.#coerceKey(item.key),
             value: item.value,
             expireAt: item.expireAt,
         }));
 
         const opts = await this.#opts('batchPut', args);
-        // Per-item expiry, which the top-level scan in `#opts` cannot see. A
-        // handle's `write` level already carries expiries.
+        // Per-item expiry, which the top-level scan in `#opts` cannot see.
         if (
             opts.namespaceAppUuid &&
-            opts.handlePrefix === undefined &&
             coerced.some(
                 (item) => item.expireAt !== undefined && item.expireAt !== null,
             )
@@ -844,20 +424,12 @@ export class KVStoreDriver extends PuterDriver {
                 opts.namespaceAppUuid,
             );
         }
-        const { res, usage } = await this.#inRegion(
+        const { res, usage } = await this.stores.kv.batchPut(
+            {
+                items: coerced,
+                disableSharing: args.optConfig?.disableSharing,
+            },
             opts,
-            coerced.map((item) => item.key),
-            () =>
-                this.stores.kv.batchPut(
-                    {
-                        items: coerced.map((item) => ({
-                            ...item,
-                            key: this.#storeKey(item.key, opts),
-                        })),
-                        disableSharing: args.optConfig?.disableSharing,
-                    },
-                    opts,
-                ),
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -865,13 +437,11 @@ export class KVStoreDriver extends PuterDriver {
 
     async del(args: {
         key: unknown;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<boolean> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         const opts = await this.#opts('del', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.del({ key: this.#storeKey(coerced, opts) }, opts),
-        );
+        const { res, usage } = await this.stores.kv.del({ key: coerced }, opts);
         this.#meter(opts.actor, usage);
         return res;
     }
@@ -885,7 +455,7 @@ export class KVStoreDriver extends PuterDriver {
         includeTotal?: boolean;
         fetchUntilFull?: boolean;
         reverse?: boolean;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
         const opts = await this.#opts('list', args);
         // Naming what it holds is how an account with nothing left decides what
@@ -899,14 +469,6 @@ export class KVStoreDriver extends PuterDriver {
                 this.config,
             );
         }
-        const handlePrefix = opts.handlePrefix;
-        const listing = this.#foreignListing(opts);
-        if (
-            handlePrefix !== undefined &&
-            typeof args.pattern === 'string' &&
-            Buffer.byteLength(args.pattern, 'utf8') > KV_HANDLE_KEY_MAX_BYTES
-        )
-            throw handlePatternInvalid();
         const { res, usage } = await this.stores.kv.list(
             {
                 as: args.as,
@@ -914,26 +476,20 @@ export class KVStoreDriver extends PuterDriver {
                     cap: KV_MAX_LIST_LIMIT,
                     label: 'kv: limit',
                 }),
-                cursor: listing
-                    ? this.#cursorIn(args.cursor, listing)
-                    : args.cursor,
+                cursor: args.cursor,
                 pattern: args.pattern,
                 offset: args.offset,
                 includeTotal: args.includeTotal,
                 fetchUntilFull: args.fetchUntilFull,
                 reverse: args.reverse,
-                ...(handlePrefix === undefined
-                    ? {}
-                    : { keyPrefix: handlePrefix }),
             },
             opts,
         );
         this.#meter(opts.actor, usage);
-        if (!listing) return res;
-        return this.#foreignResult(res as KvListResult, args.as, listing);
+        return res;
     }
 
-    async flush(args: { optConfig?: KvOptConfig }): Promise<boolean> {
+    async flush(args: { optConfig?: { appUuid?: string } }): Promise<boolean> {
         const opts = await this.#opts('flush', args);
         const { res, usage } = await this.stores.kv.flush(opts);
         this.#meter(opts.actor, usage);
@@ -943,9 +499,9 @@ export class KVStoreDriver extends PuterDriver {
     async incr(args: {
         key: unknown;
         pathAndAmountMap: Record<string, number>;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (
             !args.pathAndAmountMap ||
             typeof args.pathAndAmountMap !== 'object'
@@ -955,14 +511,9 @@ export class KVStoreDriver extends PuterDriver {
             });
         }
         const opts = await this.#opts('incr', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.incr(
-                {
-                    key: this.#storeKey(coerced, opts),
-                    pathAndAmountMap: args.pathAndAmountMap,
-                },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.incr(
+            { key: coerced, pathAndAmountMap: args.pathAndAmountMap },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -971,9 +522,9 @@ export class KVStoreDriver extends PuterDriver {
     async decr(args: {
         key: unknown;
         pathAndAmountMap: Record<string, number>;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (
             !args.pathAndAmountMap ||
             typeof args.pathAndAmountMap !== 'object'
@@ -983,14 +534,9 @@ export class KVStoreDriver extends PuterDriver {
             });
         }
         const opts = await this.#opts('decr', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.decr(
-                {
-                    key: this.#storeKey(coerced, opts),
-                    pathAndAmountMap: args.pathAndAmountMap,
-                },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.decr(
+            { key: coerced, pathAndAmountMap: args.pathAndAmountMap },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -999,23 +545,18 @@ export class KVStoreDriver extends PuterDriver {
     async expireAt(args: {
         key: unknown;
         timestamp: number;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<boolean> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (typeof args.timestamp !== 'number') {
             throw new HttpError(400, '`timestamp` must be a number', {
                 legacyCode: 'bad_request',
             });
         }
         const opts = await this.#opts('expireAt', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.expireAt(
-                {
-                    key: this.#storeKey(coerced, opts),
-                    timestamp: args.timestamp,
-                },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.expireAt(
+            { key: coerced, timestamp: args.timestamp },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -1024,20 +565,18 @@ export class KVStoreDriver extends PuterDriver {
     async expire(args: {
         key: unknown;
         ttl: number;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<boolean> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (typeof args.ttl !== 'number') {
             throw new HttpError(400, '`ttl` must be a number (seconds)', {
                 legacyCode: 'bad_request',
             });
         }
         const opts = await this.#opts('expire', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.expire(
-                { key: this.#storeKey(coerced, opts), ttl: args.ttl },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.expire(
+            { key: coerced, ttl: args.ttl },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -1047,24 +586,22 @@ export class KVStoreDriver extends PuterDriver {
         key: unknown;
         pathAndValueMap: Record<string, unknown>;
         ttl?: number | null;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (!args.pathAndValueMap || typeof args.pathAndValueMap !== 'object') {
             throw new HttpError(400, 'Missing or invalid `pathAndValueMap`', {
                 legacyCode: 'bad_request',
             });
         }
         const opts = await this.#opts('update', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.update(
-                {
-                    key: this.#storeKey(coerced, opts),
-                    pathAndValueMap: args.pathAndValueMap,
-                    ttl: args.ttl,
-                },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.update(
+            {
+                key: coerced,
+                pathAndValueMap: args.pathAndValueMap,
+                ttl: args.ttl,
+            },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -1073,23 +610,18 @@ export class KVStoreDriver extends PuterDriver {
     async add(args: {
         key: unknown;
         pathAndValueMap: Record<string, unknown>;
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (!args.pathAndValueMap || typeof args.pathAndValueMap !== 'object') {
             throw new HttpError(400, 'Missing or invalid `pathAndValueMap`', {
                 legacyCode: 'bad_request',
             });
         }
         const opts = await this.#opts('add', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.add(
-                {
-                    key: this.#storeKey(coerced, opts),
-                    pathAndValueMap: args.pathAndValueMap,
-                },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.add(
+            { key: coerced, pathAndValueMap: args.pathAndValueMap },
+            opts,
         );
         this.#meter(opts.actor, usage);
         return res;
@@ -1098,27 +630,23 @@ export class KVStoreDriver extends PuterDriver {
     async remove(args: {
         key: unknown;
         paths: string[];
-        optConfig?: KvOptConfig;
+        optConfig?: { appUuid?: string };
     }): Promise<unknown> {
-        const coerced = this.#coerceKey(args.key, args);
+        const coerced = this.#coerceKey(args.key);
         if (!Array.isArray(args.paths) || args.paths.length === 0) {
             throw new HttpError(400, 'Missing or invalid `paths`', {
                 legacyCode: 'bad_request',
             });
         }
         const opts = await this.#opts('remove', args);
-        const { res, usage } = await this.#inRegion(opts, [coerced], () =>
-            this.stores.kv.remove(
-                { key: this.#storeKey(coerced, opts), paths: args.paths },
-                opts,
-            ),
+        const { res, usage } = await this.stores.kv.remove(
+            { key: coerced, paths: args.paths },
+            opts,
         );
         this.#meter(opts.actor, usage);
-        // The result is the entry's value, so a delete-only grant gets none. A
-        // handle's `write` level reads too.
+        // The result is the entry's value, so a delete-only grant gets none.
         if (
             opts.namespaceAppUuid &&
-            opts.handlePrefix === undefined &&
             !(await this.services.permission.check(
                 opts.actor!,
                 appDataPermission(opts.namespaceAppUuid, 'kv', 'get'),

src/backend/drivers/notification/NotificationDriver.ts

@@ -36,7 +36,6 @@ import {
 } from '../../services/notification/notificationAudience.js';
 import {
     NOTIFICATION_VALUE_MAX_BYTES,
-    OUTSIDE_ACCOUNT_MAILBOX_TYPES,
     resolveNotificationWrite,
     type NotificationTypeName,
 } from '../../services/notification/notificationTypes.js';
@@ -222,13 +221,7 @@ export class NotificationDriver extends PuterDriver {
             scope: MailboxScope | null;
             filter?: string;
             onlyUnacknowledged?: boolean;
-            excludeTypes?: readonly string[];
         } = { limit, scope };
-        // The whole mailbox, or a slice naming no app, is the desktop's view of
-        // it, which leaves out the types only an app has a use for. A slice
-        // naming the app still returns them.
-        if (scope === null || scope.appUid === undefined)
-            query.excludeTypes = OUTSIDE_ACCOUNT_MAILBOX_TYPES;
 
         switch (predicateName) {
             case 'unseen':

src/backend/services/events/EventsService.test.ts

@@ -51,9 +51,8 @@ import {
     EVENTS_UNSUBSCRIBE_VERB,
     type DeliveryEnvelope,
     type EventSocket,
-    type KvDispatchOptions,
 } from './EventsService.js';
-import { kvSharePermission } from '../kvShare/kvShares.js';
+import { kvSharePermission } from './kvShares.js';
 import { FILTER_EVALUATIONS_PER_EVENT } from './matcher.js';
 import { SUBSCRIPTION_CACHE_TTL_MS } from './subscriptionCache.js';
 import { kvAnchorToken } from './subjects.js';
@@ -204,15 +203,6 @@ let handles: Map<string, KvShareHandle>;
 
 const kvShareHandleStore = {
     getByHandle: async (handle: string) => handles.get(handle) ?? null,
-    getLive: async (handle: string) => {
-        const row = handles.get(handle);
-        if (!row || row.revokedAt !== null) return null;
-        return {
-            row,
-            ownerUuid: `user-${row.ownerUserId}`,
-            ownerSuspended: false,
-        };
-    },
 };
 
 /** Apps the cross-app gate can be asked about, and what they share. */
@@ -2118,7 +2108,6 @@ it('sends only the projected shape, never an internal row', async () => {
         'subject',
         'ts',
         'uid',
-        'viaWorker',
     ]);
     expect(sent[0].envelope.event).not.toHaveProperty('userId');
 });
@@ -2565,47 +2554,6 @@ describe('delivering a kv change', () => {
         expect(sent).toEqual([]);
     });
 
-    it('tells a subscriber the change was theirs only when they made it', async () => {
-        vi.useFakeTimers();
-        await subscribeKv(`kv:${OWN_APP}:cart`);
-        const write = (options: KvDispatchOptions) =>
-            service.dispatchKv(
-                {
-                    userId,
-                    namespace: `v1:user-${userId}:${OWN_APP}`,
-                    keys: ['cart'],
-                    op: 'set',
-                },
-                options,
-            );
-
-        // One window each: writes to one key inside a window coalesce.
-        for (const options of [
-            { actingUserId: userId },
-            { actingUserId: userId + 1 },
-            {},
-            { actingUserId: userId, viaWorker: true },
-        ]) {
-            await write(options);
-            await vi.advanceTimersByTimeAsync(EVENTS_COALESCE_WINDOW_MS + 1);
-        }
-
-        expect(
-            sent.map(({ envelope }) => {
-                const { self, viaWorker } = envelope.event as {
-                    self: boolean;
-                    viaWorker: boolean;
-                };
-                return { self, viaWorker };
-            }),
-        ).toEqual([
-            { self: true, viaWorker: false },
-            { self: false, viaWorker: false },
-            { self: false, viaWorker: false },
-            { self: true, viaWorker: true },
-        ]);
-    });
-
     it('sends only the projected shape', async () => {
         vi.useFakeTimers();
         await subscribeKv(`kv:${OWN_APP}:cart`);
@@ -2621,7 +2569,6 @@ describe('delivering a kv change', () => {
             'seq',
             'subject',
             'ts',
-            'viaWorker',
         ]);
     });
 });
@@ -2896,7 +2843,6 @@ describe('the cross-app kv gate', () => {
             'seq',
             'subject',
             'ts',
-            'viaWorker',
         ]);
     });
 
@@ -3005,10 +2951,8 @@ describe('cross-user kv handles', () => {
             appUid: OWN_APP,
             keyPrefix: PREFIX,
             permission,
-            label: null,
             createdAt: 0,
             revokedAt: null,
-            revokedBy: null,
             ...overrides,
         };
         handles.set(row.handle, row);

src/backend/services/events/EventsService.ts

@@ -31,6 +31,9 @@ import {
     EVENTS_HANDLER_DEPTH,
     EVENTS_HANDLER_PUBLISH_BATCH,
     EVENTS_HANDLER_PUBLISH_LIMIT,
+    EVENTS_KV_HANDLE_LIMIT,
+    EVENTS_KV_HANDLES_PER_APP,
+    EVENTS_KV_HANDLES_PER_USER,
     EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT,
     EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT,
     EVENTS_KV_VALUE_MAX_BYTES,
@@ -50,6 +53,7 @@ import {
     isAccessTokenActor,
     isAccountContext,
     makeActor,
+    userRelatedActor,
     type Actor,
 } from '../../core/actor.js';
 import { HttpError, isHttpError } from '../../core/http/HttpError.js';
@@ -58,12 +62,15 @@ import type {
     ReanchorInput,
     SuspendedReason,
 } from '../../stores/events/DurableSubscriptionStore.js';
-import type { LiveKvShareHandle } from '../../stores/events/KvShareHandleStore.js';
 import {
     DurableQuotaRaceLost,
     HANDLER_SETTLE_BATCH,
     isSuspendedReason,
 } from '../../stores/events/DurableSubscriptionStore.js';
+import type {
+    KvShareHandle,
+    KvShareHandleListOptions,
+} from '../../stores/events/KvShareHandleStore.js';
 import {
     HANDLER_NAME_MAX_LENGTH,
     hashContent,
@@ -91,7 +98,10 @@ import {
     type SubscriptionTarget,
 } from '../../stores/events/types.js';
 import type { FSEntry } from '../../stores/fs/FSEntry.js';
-import { parseKvNamespace } from '../../stores/systemKv/SystemKVStore.js';
+import {
+    KV_GLOBAL_APP_KEY,
+    parseKvNamespace,
+} from '../../stores/systemKv/SystemKVStore.js';
 import { awaitLater } from '../../util/concurrency.js';
 import {
     openCursor,
@@ -101,17 +111,13 @@ import {
 import type { AclMode, ResourceDescriptor } from '../acl/ACLService.js';
 import { resolveNode } from '../fs/resolveNode.js';
 import { maskUnderAnchor } from '../fs/sharePathMask.js';
-import { actorPlanId, assertActorHasCredits } from '../metering/enforcement.js';
+import { assertActorHasCredits } from '../metering/enforcement.js';
 import {
     canViewNotification,
     notificationRowScope,
     ownedAppUids,
 } from '../notification/notificationAudience.js';
 import { notificationsFoldInEnabled } from '../notification/notificationSocket.js';
-import {
-    inAccountMailbox,
-    OUTSIDE_ACCOUNT_MAILBOX_TYPES,
-} from '../notification/notificationTypes.js';
 import {
     appSocketRoom,
     type SocketSpecifier,
@@ -190,10 +196,18 @@ import {
 } from './registry.js';
 import { SubscriptionCache } from './subscriptionCache.js';
 import {
+    assertBoundedManageGrant,
+    assertShareableAppUid,
+    assertShareablePermission,
+    assertShareablePrefix,
+    kvShareAppDelegateImplicator,
     kvShareGrantCovers,
+    kvShareManageNamespaceRoot,
+    kvShareManagePermission,
+    kvShareOwnerImplicator,
     kvSharePermission,
     relativeToKvShareRoot,
-} from '../kvShare/kvShares.js';
+} from './kvShares.js';
 import {
     KV_MATCH_SEPARATOR,
     NOTIF_MATCH_SEPARATOR,
@@ -202,7 +216,6 @@ import {
     isKvToken,
     isNotifToken,
     kvHandleFromSubject,
-    notifMatchSpansEveryApp,
     parseSubject,
     type FsOp,
     type ParsedSubject,
@@ -419,6 +432,35 @@ export interface DurableSubscriptionView extends SubscriptionView {
     suspendedReason: string | null;
 }
 
+/** Body of the handle-minting surface. The grantee is named either way. */
+export interface MintKvHandleRequest {
+    granteeUsername?: unknown;
+    granteeUid?: unknown;
+    appUid?: unknown;
+    prefix?: unknown;
+}
+
+/**
+ * What minting returns. Only the handle and the region it covers: the owner
+ * already knows the rest, and the grantee is handed this verbatim, so anything
+ * else here would be something the handle exists to not say.
+ */
+export interface MintedKvHandle {
+    handle: string;
+    prefix: string;
+}
+
+/**
+ * One handle as its owner sees it, revoked ones included — they are the record
+ * of what was shared and when it stopped.
+ */
+export interface KvShareHandleView extends MintedKvHandle {
+    appUid: string;
+    granteeUsername: string | null;
+    createdAt: number;
+    revokedAt: number | null;
+}
+
 export type VerbAck<T extends object> =
     | ({ ok: true } & T)
     | { ok: false; error: { code: string; message: string } };
@@ -534,8 +576,6 @@ export interface FsDispatchOptions {
     actingUserId?: number;
     /** Handler runs behind the write; see `Actor.handlerDepth`. */
     handlerDepth?: number;
-    /** The write was made by server-side code; see `viaWorkerOf`. */
-    viaWorker?: boolean;
     /** Present only for a move: where the entry lived before it, lazily. */
     movedFrom?: {
         path: string;
@@ -556,8 +596,6 @@ export interface FsDispatchOptions {
 export interface KvDispatchOptions {
     /** Who performed the write, for the `self` flag. */
     actingUserId?: number;
-    /** The write was made by server-side code; see `viaWorkerOf`. */
-    viaWorker?: boolean;
     /** See {@link FsDispatchOptions.forwarded}. */
     forwarded?: true;
     /** Carried over from the emitting region so both copies share one id/ts. */
@@ -595,9 +633,6 @@ export interface KvDispatchInput {
     noShareKeys?: readonly string[];
     /** Handler runs behind the write; see `Actor.handlerDepth`. */
     handlerDepth?: number;
-    /** Who made the change; the listener hands it on as an option. */
-    actingUserId?: number;
-    viaWorker?: true;
 }
 
 interface RouteLimits {
@@ -796,6 +831,19 @@ const handlerAppRequired = (): HttpError =>
         legacyCode: 'events_handler_app_required',
     });
 
+/**
+ * Listing and revoking are the owner's, and an app's only where the handle is
+ * the app's own: its namespace, its user, and a delegation it still holds.
+ * Anything else — another app, a token an app issued, a handle outside the
+ * namespace — reads as somebody else's surface.
+ */
+const handleOwnerOnly = (): HttpError =>
+    new HttpError(
+        403,
+        'Only the account, or the app whose namespace this is, may manage share handles',
+        { legacyCode: 'events_kv_handle_owner_only' },
+    );
+
 /** A scoped token, whoever issued it: neither the account nor the app. */
 const eventsWorkerOwnerOnly = (): HttpError =>
     new HttpError(
@@ -804,6 +852,62 @@ const eventsWorkerOwnerOnly = (): HttpError =>
         { legacyCode: 'events_worker_owner_only' },
     );
 
+/**
+ * An app minting is delegation, and the `manage:` grant on the region is the
+ * consent for it. Without one there is nothing authorizing the app to dispose
+ * of its user's data, whatever the user themselves could do here.
+ */
+const handleNotDelegated = (): HttpError =>
+    new HttpError(
+        403,
+        'This app has not been given permission to share this data',
+        { legacyCode: 'events_kv_handle_not_delegated' },
+    );
+
+/**
+ * A delegation is the app's to hold, not to pass on: a token it minted may
+ * carry the `manage:` permission and still not mint through it. The user's own
+ * token is not this case — it acts for the user, who needs no delegation.
+ */
+const handleAccessTokenForbidden = (): HttpError =>
+    new HttpError(403, 'An access token may not mint a share handle', {
+        legacyCode: 'forbidden',
+    });
+
+/**
+ * An app addresses exactly one key-value namespace — its own, under its user —
+ * so that is the only one it can hand a region of out.
+ */
+const handleOutsideNamespace = (): HttpError =>
+    new HttpError(403, 'An app may only share its own key-value data', {
+        legacyCode: 'events_kv_handle_outside_namespace',
+    });
+
+/**
+ * A temporary account holds no share handles: the grant outlives the session
+ * that made it, and there is no account left behind it to take one back.
+ */
+const kvHandleNeedsAccount = (): HttpError =>
+    new HttpError(403, 'A temporary account may not share its key-value data', {
+        legacyCode: 'events_kv_handle_requires_account',
+    });
+
+/**
+ * Past a handle ceiling. One code for both of them — the remedy is the same,
+ * revoke something — with the message saying which one it was.
+ */
+const handleQuotaReached = (
+    limit: number,
+    scope: 'account' | 'app',
+): HttpError =>
+    new HttpError(
+        409,
+        scope === 'app'
+            ? `An app may hold out ${limit} share handles for one account`
+            : `An account may hold out ${limit} share handles at a time`,
+        { legacyCode: 'events_kv_handle_limit_reached' },
+    );
+
 /**
  * Deploying an app's code is the developer's, and an app token cannot borrow
  * its user's ownership of some other app. Same answer for an app that is not
@@ -1370,17 +1474,6 @@ export class EventsService extends PuterService {
             });
         });
 
-        // A retired handle is a dead address: what was made through it ends,
-        // even where another grant still covers the region. Awaited by the
-        // emitter, so a revoke returns once its subscriptions are settled.
-        this.clients.event.on('kv.share.retired', async (_key, data) => {
-            try {
-                await this.settleRetiredKvHandles(data);
-            } catch (err) {
-                console.warn('[events] retired-handle settle failed', err);
-            }
-        });
-
         // A deleted app's rows can never deliver again — the grant identity
         // they are re-checked under no longer resolves — so they are torn
         // down rather than left to cost their holder an anchor slot forever.
@@ -1414,17 +1507,9 @@ export class EventsService extends PuterService {
         // a service. Same posture as the FS hook: post-commit, and nothing here
         // can fail the write that produced it.
         this.clients.event.on('kv.mutated', (_key, data) => {
-            const input = data as KvDispatchInput;
-            void (async () => {
-                try {
-                    await this.dispatchKv(input, {
-                        actingUserId: input.actingUserId,
-                        viaWorker: input.viaWorker === true,
-                    });
-                } catch (err) {
-                    console.warn('[events] kv dispatch failed', err);
-                }
-            })();
+            void this.dispatchKv(data as KvDispatchInput).catch((err) => {
+                console.warn('[events] kv dispatch failed', err);
+            });
         });
 
         // Emitted once the row is written, so a delivery never names a
@@ -1435,6 +1520,19 @@ export class EventsService extends PuterService {
             });
         });
 
+        // Owning a key-value namespace is holding every share grant over it,
+        // which is what lets its owner mint a handle on their own data.
+        this.services.permission.registerImplicator(kvShareOwnerImplicator());
+
+        // Lets an app-under-user actor exercise a share grant its user holds,
+        // scoped to the app the grant's namespace names.
+        this.services.permission.registerImplicator(
+            kvShareAppDelegateImplicator({
+                userHolds: (actor, permission) =>
+                    this.services.permission.check(actor, permission),
+            }),
+        );
+
         this.#armExpirySweep();
         this.#armPendingSweep();
         this.#armCreditSweep();
@@ -1836,8 +1934,15 @@ export class EventsService extends PuterService {
     }
 
     /** The plan this actor is on, or `null` where there are no plans. */
-    #planId(actor: Actor): Promise<string | null> {
-        return actorPlanId(this.services.metering, actor);
+    async #planId(actor: Actor): Promise<string | null> {
+        const metering = this.services.metering;
+        if (!metering) return null;
+        try {
+            return (await metering.getActorSubscription(actor)).id;
+        } catch (err) {
+            console.warn('[events] could not resolve a plan', err);
+            return null;
+        }
     }
 
     /**
@@ -1942,16 +2047,11 @@ export class EventsService extends PuterService {
         );
 
         // One extra row answers "is there another page" without a count.
-        // The generic slice is the desktop's view of the mailbox, so it leaves
-        // out the types kept off the desktop, as the live delivery does.
         const rows = await this.stores.notification.listScoped(user.id, {
             audience: scope.audience,
             appUid: scope.appUid,
             after: Number.isFinite(cursored) ? cursored : null,
             limit: limit + 1,
-            ...(scope.appUid === undefined
-                ? { excludeTypes: OUTSIDE_ACCOUNT_MAILBOX_TYPES }
-                : {}),
         });
 
         const page = rows.slice(0, limit);
@@ -2299,6 +2399,373 @@ export class EventsService extends PuterService {
         return { appUid, removed, suspended };
     }
 
+    // -- Cross-user key-value handles --------------------------------
+
+    /**
+     * Hand another user a watchable region of this account's key-value data.
+     *
+     * Two writes, in this order: the grant, which is the authorization and
+     * carries its own `manage:` check and its own refusal to grant to yourself,
+     * and then the handle, which is only a name for it. A handle whose grant
+     * never landed would be a name for nothing; a grant whose handle never
+     * landed is unaddressable, since a handle is the only thing that can name
+     * this family.
+     *
+     * An app may mint too, bounded the way sharing bounds an app handing out
+     * its user's files: authority is the user's, asked of the user behind the
+     * actor and never of the app, and reach is what the credential itself
+     * holds. Here reach is structural — an app addresses one namespace — so it
+     * is asserted rather than worked out, and the app's own consent to delegate
+     * is a `manage:` grant on the region.
+     */
+    async mintKvHandle(
+        actor: Actor,
+        request: MintKvHandleRequest,
+    ): Promise<MintedKvHandle> {
+        if (!this.enabled) throw disabled();
+        if (!this.kvHandlesEnabled) throw kvShareHandleDisabled();
+
+        const owner = actor.user;
+        if (!owner?.uuid || owner.id === undefined) throw disabled();
+        // `undefined` is an app that could not be resolved, not the absence of
+        // one — reading it as an account session is what would hand an app a
+        // surface bounded on the app it is acting as.
+        const app = actor.effectiveApp;
+        if (app === undefined) throw handleOwnerOnly();
+        // An account's surface is the account's, and a token scoped to less
+        // than its issuer holds is not the account. A token an app issued is
+        // refused by the delegation check below, which has its own answer.
+        if (app === null && !isAccountContext(actor)) throw handleOwnerOnly();
+
+        // The budget is the user's, so an app spends its user's slots rather
+        // than a machine-rate allowance of its own.
+        await this.#spendHandleBudget(owner.id);
+
+        const keyPrefix = assertShareablePrefix(request?.prefix);
+        const appUid = this.#mintNamespace(app, request);
+        const grantee = await this.#resolveGrantee(request);
+
+        const permission = assertShareablePermission(
+            kvSharePermission(owner.uuid, appUid, keyPrefix),
+        );
+        // Before the idempotent answer below, or an app that lost its
+        // delegation could read back a handle it may no longer hand out.
+        if (app) await this.#assertKvShareDelegated(actor, permission);
+
+        // Resolved before the idempotent answer below, so a plan that holds
+        // none is refused whatever it asks for. Kept behind the delegation
+        // check above: an app with no delegation must not learn anything
+        // about the account's plan.
+        const quota = await this.#handleQuota(actor);
+
+        // The same region minted again for the same grantee is the same
+        // capability, not a second one — handing back what already exists is
+        // what keeps two handles from ever sharing one permission row. The
+        // ceiling counts slots, and this takes none, so it is not asked.
+        const existing = await this.stores.kvShareHandle.findLive({
+            ownerUserId: owner.id,
+            granteeUserId: grantee.id,
+            appUid,
+            keyPrefix,
+        });
+        if (existing)
+            return { handle: existing.handle, prefix: existing.keyPrefix };
+
+        await this.#assertHandleCeiling(owner.id, appUid, quota);
+
+        // The user behind the app, so the authority checked is theirs and the
+        // issuer recorded is them. Which app acted is carried separately: it
+        // belongs on the audit row, not in the grant's authority.
+        await this.services.permission.grantUserUserPermission(
+            userRelatedActor(actor),
+            grantee.username,
+            permission,
+            {},
+            { reason: 'kv share handle', appUid: app?.uid },
+        );
+
+        const row = await this.stores.kvShareHandle.mint({
+            ownerUserId: owner.id,
+            granteeUserId: grantee.id,
+            appUid,
+            keyPrefix,
+            permission,
+        });
+        return { handle: row.handle, prefix: row.keyPrefix };
+    }
+
+    /**
+     * Which namespace a mint may name. An app reaches `v1:<user>:<its own app>`
+     * and nothing else, so a request naming another one is refused rather than
+     * quietly minted somewhere the app cannot even write.
+     */
+    #mintNamespace(
+        app: Actor['effectiveApp'],
+        request: MintKvHandleRequest,
+    ): string {
+        const named = parseAppUid(request?.appUid);
+        if (!app) return assertShareableAppUid(named ?? KV_GLOBAL_APP_KEY);
+        if (named !== null && named !== app.uid) throw handleOutsideNamespace();
+        return app.uid;
+    }
+
+    /**
+     * Whether this app was given the region to hand out. The `manage:` grant is
+     * the user's consent, and prefix implication makes one taken on a region
+     * cover the keys beneath it — so a handle deeper than the consent is still
+     * inside it, and one above it is not.
+     */
+    async #assertKvShareDelegated(
+        actor: Actor,
+        permission: string,
+    ): Promise<void> {
+        // Consequential enough to require the app's own session, whatever a
+        // token it minted happens to carry.
+        if (isAccessTokenActor(actor)) throw handleAccessTokenForbidden();
+        // The consent surface refuses a namespace-root delegation because no
+        // prompt can describe it; refused here too, so a row written any other
+        // way cannot authorize a mint.
+        assertBoundedManageGrant(kvShareManagePermission(permission));
+        const delegated = await this.services.permission.canManagePermission(
+            actor,
+            permission,
+        );
+        if (!delegated) throw handleNotDelegated();
+        // `canManagePermission` walks ancestors, so a namespace-root grant
+        // written by any path other than the consent surface would otherwise
+        // authorize a mint anywhere in the namespace, bounded region or not.
+        const unbounded = await this.services.permission.check(
+            actor,
+            kvShareManageNamespaceRoot(permission),
+        );
+        if (unbounded) throw handleNotDelegated();
+    }
+
+    /**
+     * Take a shared region back.
+     *
+     * The grant goes first — the subtree with it, since a deeper grant would
+     * leave access to part of a region that has just been withdrawn — and the
+     * handle is retired after. Removing the grant is what actually settles the
+     * subscriptions, and it is the only half that stops delivery, so it is the
+     * half that must not be able to fail after the other has succeeded. In that
+     * order both steps are idempotent and a failure anywhere is a retry: the
+     * reverse leaves a handle nothing can address standing on a grant
+     * everything still passes, and no way to try again.
+     *
+     * Not gated on the feature flag. Withdrawing access only ever narrows, and
+     * an install that turned handles off must still be able to retire the ones
+     * it has.
+     */
+    async revokeKvHandle(
+        actor: Actor,
+        handle: unknown,
+    ): Promise<{ handle: string; revokedAt: number }> {
+        if (!this.enabled) throw disabled();
+        const owner = actor.user;
+        if (owner?.id === undefined) throw disabled();
+        // `undefined` is an app that could not be resolved, not the absence of
+        // one — reading it as an account session is what would hand an app the
+        // account's whole surface.
+        const app = actor.effectiveApp;
+        if (app === undefined) throw handleOwnerOnly();
+        // A delegation is the app's to hold, not to pass on, so a token an app
+        // issued is refused here as it is on the mint path — and a user's own
+        // token acts for the user only when it carries the user's whole reach.
+        if (isAccessTokenActor(actor) && !isAccountContext(actor))
+            throw handleOwnerOnly();
+
+        await this.#spendHandleBudget(owner.id);
+
+        const named = typeof handle === 'string' ? handle : '';
+        const share = await this.stores.kvShareHandle.getByHandle(named);
+        // Unknown and somebody else's read the same way, so revoking cannot be
+        // used to find out that a handle exists.
+        if (!share || share.ownerUserId !== owner.id)
+            throw unknownKvShareHandle(named);
+        // An app reaches one namespace, so a handle outside it is not its to
+        // take back — checked after the owner test, which must answer first.
+        if (app && share.appUid !== app.uid) throw handleOwnerOnly();
+        // The same consent the mint took: a withdrawn delegation withdraws the
+        // app's surface on the region with it.
+        if (app) await this.#assertKvShareDelegated(actor, share.permission);
+
+        const grantee = await this.stores.user.getById(share.granteeUserId);
+        if (!grantee?.username)
+            throw new HttpError(500, 'The grantee of this handle is gone', {
+                legacyCode: 'internal_error',
+            });
+        await this.services.permission.revokeUserUserPermissionSubtree(
+            userRelatedActor(actor),
+            grantee.username,
+            share.permission,
+            { reason: 'kv share handle revoked', appUid: app?.uid },
+        );
+
+        const revoked = await this.stores.kvShareHandle.retire(named, owner.id);
+        if (!revoked?.revokedAt) throw unknownKvShareHandle(named);
+
+        // A narrower handle to the same grantee shares this one's permission
+        // row whenever its region nests under it, and the subtree revoke
+        // above just withdrew that row — so its grant is already gone even
+        // though its own row still reads live.
+        await this.#retireCoveredHandles(revoked);
+
+        return { handle: revoked.handle, revokedAt: revoked.revokedAt };
+    }
+
+    /**
+     * Every other live handle to this grantee that the just-withdrawn grant
+     * covered. Coverage runs on the permission string, whose third component is
+     * the namespace app uid, so a covered handle is always inside the same
+     * one.
+     */
+    async #retireCoveredHandles(revoked: KvShareHandle): Promise<void> {
+        const siblings =
+            await this.stores.kvShareHandle.listLiveForOwnerAndGrantee(
+                revoked.ownerUserId,
+                revoked.granteeUserId,
+            );
+        await Promise.all(
+            siblings
+                .filter((row) =>
+                    kvShareGrantCovers(revoked.permission, row.permission),
+                )
+                .map((row) =>
+                    this.stores.kvShareHandle.retire(
+                        row.handle,
+                        revoked.ownerUserId,
+                    ),
+                ),
+        );
+    }
+
+    /**
+     * What this account has shared out of its key-value data, retired handles
+     * included: they are the only record of what was shared and when it
+     * stopped. The grantee has no listing of their own — what they hold is the
+     * handle they were given.
+     */
+    async listKvHandles(
+        actor: Actor,
+        options: KvShareHandleListOptions = {},
+    ): Promise<PageResult<KvShareHandleView>> {
+        if (!this.enabled) throw disabled();
+        const owner = actor.user;
+        if (owner?.id === undefined) throw disabled();
+        const app = actor.effectiveApp;
+        if (app === undefined) throw handleOwnerOnly();
+        if (isAccessTokenActor(actor) && !isAccountContext(actor))
+            throw handleOwnerOnly();
+
+        // An app sees its own namespace and nothing else; an account session
+        // sees across apps, which is what makes the account the surface for a
+        // row whose app is long gone. Listing disposes of nothing, so the gate
+        // is app-ness and the namespace rather than the region's delegation.
+        const page = await this.stores.kvShareHandle.listForOwner(owner.id, {
+            limit: options.limit,
+            cursor: options.cursor,
+            includeTotal: options.includeTotal,
+            appUid: app?.uid ?? null,
+        });
+        const grantees = await this.stores.user.getByIds([
+            ...new Set(page.items.map((row) => row.granteeUserId)),
+        ]);
+
+        return {
+            ...page,
+            items: page.items.map((row) => ({
+                handle: row.handle,
+                prefix: row.keyPrefix,
+                appUid: row.appUid,
+                granteeUsername:
+                    grantees.get(row.granteeUserId)?.username ?? null,
+                createdAt: row.createdAt,
+                revokedAt: row.revokedAt,
+            })),
+        };
+    }
+
+    /** Who a mint is for. Named by username or uuid; unknown reads as absent. */
+    async #resolveGrantee(
+        request: MintKvHandleRequest,
+    ): Promise<{ id: number; username: string }> {
+        const username =
+            typeof request?.granteeUsername === 'string'
+                ? request.granteeUsername.trim()
+                : '';
+        const uid =
+            typeof request?.granteeUid === 'string'
+                ? request.granteeUid.trim()
+                : '';
+        if (!username && !uid)
+            throw badRequest(
+                'Name the grantee with `granteeUsername` or `granteeUid`',
+                'bad_request',
+            );
+
+        const user = username
+            ? await this.stores.user.getByUsername(username)
+            : await this.stores.user.getByUuid(uid);
+        if (!user?.username || user.id === undefined)
+            throw new HttpError(404, 'user_does_not_exist', {
+                legacyCode: 'subject_does_not_exist',
+            });
+        return { id: user.id, username: user.username };
+    }
+
+    /**
+     * How many handles this caller's plan lets the account hold out, in total
+     * and in one namespace. Resolved before the idempotent answer on the mint
+     * path, so a plan that may hold none is refused whatever it asks for.
+     *
+     * A deployment with no metering has no plans to read, and is held to the
+     * paid caps.
+     */
+    async #handleQuota(actor: Actor): Promise<TieredQuota> {
+        const plan = await this.#planId(actor);
+        if (plan !== null && limitFor(EVENTS_KV_HANDLES_PER_USER, plan) === 0)
+            throw kvHandleNeedsAccount();
+        return {
+            perUser: limitFor(EVENTS_KV_HANDLES_PER_USER, plan),
+            perApp: limitFor(EVENTS_KV_HANDLES_PER_APP, plan),
+        };
+    }
+
+    /**
+     * Whether this account may hold out another share handle, in total and in
+     * the namespace this mint names. Retired ones do not count: the row stays
+     * as the record of what was shared, not as a slot. Check-then-act: two
+     * mints racing past it can both proceed, which the mint budget bounds well
+     * enough for an abuse backstop.
+     */
+    async #assertHandleCeiling(
+        userId: number,
+        appUid: string,
+        quota: TieredQuota,
+    ): Promise<void> {
+        const live = await this.stores.kvShareHandle.countLiveForOwner(
+            userId,
+            appUid,
+        );
+        if (live.total >= quota.perUser)
+            throw handleQuotaReached(quota.perUser, 'account');
+        // The global namespace is the account's own shelf rather than an
+        // app's, so the account cap is its only bound — which is also what
+        // keeps that cap reachable without naming a namespace.
+        if (appUid !== KV_GLOBAL_APP_KEY && live.forApp >= quota.perApp)
+            throw handleQuotaReached(quota.perApp, 'app');
+    }
+
+    async #spendHandleBudget(userId: number): Promise<void> {
+        const ok = await checkRateLimit(
+            `${EVENTS_KV_HANDLE_LIMIT.scope}:${userId}`,
+            EVENTS_KV_HANDLE_LIMIT.limit,
+            EVENTS_KV_HANDLE_LIMIT.window,
+        );
+        if (!ok) throw tooManyCalls();
+    }
+
     // -- Suspension --------------------------------------------------
 
     /**
@@ -3080,11 +3547,9 @@ export class EventsService extends PuterService {
      * keyspace that is matters: the row is indexed under the **owner**, because
      * a write only ever knows whose namespace it touched.
      *
-     * Authority is the grant, never the handle: an actor holding the grant at
-     * any level may subscribe, and one who does not is told the handle is not
-     * there rather than that it is theirs to want. The handle is also bound to
-     * its holder, so another user whose own grant overlaps the region cannot
-     * use it.
+     * Authority is the grant, never the handle: an actor holding the mirrored
+     * permission may subscribe, and one who does not is told the handle is not
+     * there rather than that it is theirs to want.
      */
     async #resolveKvHandleSubscribe(
         actor: Actor,
@@ -3096,31 +3561,17 @@ export class EventsService extends PuterService {
         const share = await this.stores.kvShareHandle.getByHandle(handle);
         if (!share || share.revokedAt !== null)
             throw unknownKvShareHandle(handle);
-        if (
-            actor.user?.id !== share.granteeUserId &&
-            actor.user?.id !== share.ownerUserId
-        )
-            throw unknownKvShareHandle(handle);
 
-        const owner = await this.stores.user.getById(share.ownerUserId);
-        if (!owner?.uuid) throw unknownKvShareHandle(handle);
-
-        // Watching is the lowest level, so every level answers it; storing it
-        // rather than the handle's own grant is what lets a level change leave
-        // the subscription alone.
-        const watch = kvSharePermission(
-            owner.uuid,
-            share.appUid,
-            share.keyPrefix,
-            'watch',
-        );
         const held = await kvSharedRegionAuthorized(
             actor,
-            watch,
+            share.permission,
             this.#kvShareDeps(),
         );
         if (!held) throw unknownKvShareHandle(handle);
 
+        const owner = await this.stores.user.getById(share.ownerUserId);
+        if (!owner?.uuid) throw unknownKvShareHandle(handle);
+
         const anchor = resolveKvHandleAnchor(parsed, {
             ownerUserUuid: owner.uuid,
             appUid: share.appUid,
@@ -3139,7 +3590,7 @@ export class EventsService extends PuterService {
             ownerUserId: share.ownerUserId,
             // The grant string rather than a mode: it is what a revoke names,
             // and what the delivery re-check asks again.
-            permission: watch,
+            permission: share.permission,
             subject: anchor.subject,
         };
     }
@@ -3265,7 +3716,6 @@ export class EventsService extends PuterService {
             id: options.id ?? randomUUID(),
             ts: options.ts ?? Date.now(),
             handlerDepth: options.handlerDepth,
-            viaWorker: options.viaWorker === true,
         };
 
         const { local, remote } =
@@ -3283,7 +3733,6 @@ export class EventsService extends PuterService {
                 family: 'fs',
                 ownerUserId,
                 actingUserId: options.actingUserId,
-                ...(context.viaWorker ? { viaWorker: true as const } : {}),
                 id: context.id,
                 ts: context.ts,
                 fs: {
@@ -3374,7 +3823,6 @@ export class EventsService extends PuterService {
             id: options.forwarded && options.id ? options.id : randomUUID(),
             ts,
             handlerDepth: input.handlerDepth,
-            viaWorker: options.viaWorker === true,
             ...(noShareKeys.has(kvKey) ? { noShare: true as const } : {}),
         }));
         const carried: Array<{ value: unknown } | undefined> = [];
@@ -3417,9 +3865,6 @@ export class EventsService extends PuterService {
                         family: 'kv',
                         ownerUserId,
                         actingUserId: options.actingUserId,
-                        ...(context.viaWorker
-                            ? { viaWorker: true as const }
-                            : {}),
                         id: context.id,
                         ts: context.ts,
                         kv: {
@@ -3486,7 +3931,7 @@ export class EventsService extends PuterService {
                 subject,
                 context,
                 forKey,
-                options.actingUserId,
+                ownerUserId,
                 (matched) =>
                     this.#kvStillAuthorized(
                         matched,
@@ -3587,7 +4032,6 @@ export class EventsService extends PuterService {
                         ancestors: async () => item.fs!.movedFrom!.ancestors,
                     },
                     actingUserId: item.actingUserId,
-                    viaWorker: item.viaWorker === true,
                     forwarded: true,
                     id: item.id,
                     ts: item.ts,
@@ -3624,7 +4068,6 @@ export class EventsService extends PuterService {
                 },
                 {
                     actingUserId: item.actingUserId,
-                    viaWorker: item.viaWorker === true,
                     forwarded: true,
                     id: item.id,
                     ts: item.ts,
@@ -3680,14 +4123,10 @@ export class EventsService extends PuterService {
         );
         if (watched.length === 0) return;
 
-        const fetched = await this.stores.eventSubscription.getForTokens(
+        const rows = await this.stores.eventSubscription.getForTokens(
             userId,
             watched,
         );
-        // A subscription naming no app is the desktop's view of the mailbox.
-        const rows = inAccountMailbox(context.type)
-            ? fetched
-            : fetched.filter((row) => !notifMatchSpansEveryApp(row.match));
         if (rows.length === 0) return;
 
         await this.#route(subject, context, rows, userId, (matched) =>
@@ -4055,27 +4494,14 @@ export class EventsService extends PuterService {
     }
 
     /**
-     * Whether one row's holder may still watch the region it was made on. The
-     * handle must be live and theirs, so a retired one goes silent within the
-     * handle cache's lifetime even where a wider grant covers the region. The
-     * grant check doesn't vary by key, so it's cached under the row's anchor.
+     * Whether one row's holder may still watch the region it was made on.
+     *
+     * Held in the cross-event cache under the row's anchor, which for a shared
+     * region is the whole of what it can address: nothing above the handle is
+     * nameable, so the answer does not vary by key and one evaluation covers
+     * every event under it until a grant or a revoke moves the generation.
      */
     async #kvShareHolds(row: DispatchSubscription): Promise<boolean> {
-        const handle = kvHandleFromSubject(row.subject);
-        if (handle === null) return false;
-        let live: LiveKvShareHandle | null;
-        try {
-            live = await this.stores.kvShareHandle.getLive(handle);
-        } catch {
-            return false;
-        }
-        if (
-            !live ||
-            (live.row.granteeUserId !== row.holderUserId &&
-                live.row.ownerUserId !== row.holderUserId)
-        )
-            return false;
-
         const identity = await this.#grantIdentity(row);
         if (!identity) return false;
 
@@ -4247,37 +4673,6 @@ export class EventsService extends PuterService {
         return suspended.length;
     }
 
-    /**
-     * Take out of service every durable subscription one user, the share's
-     * owner or its holder, made through these share handles, with their
-     * backlogs. One holder-index read, bounded by the user's subscription cap.
-     * Session rows are left to the delivery re-check, which reads the handle's
-     * liveness.
-     */
-    async settleRetiredKvHandles(retired: {
-        handles: readonly string[];
-        userId: number;
-    }): Promise<number> {
-        if (!this.enabled || retired.handles.length === 0) return 0;
-        const held = await this.stores.durableSubscription.listActiveForHolder(
-            retired.userId,
-            null,
-            { includeSuspended: true },
-        );
-        const handles = new Set(retired.handles);
-        const settling = held.filter((row) => {
-            const handle = kvHandleFromSubject(row.subject);
-            return handle !== null && handles.has(handle);
-        });
-        if (settling.length === 0) return 0;
-
-        const suspended = await this.#suspend(settling, 'permission_revoked', {
-            override: RESUMABLE_REASONS,
-        });
-        await this.#notifyEnded(suspended, 'permission_revoked');
-        return suspended.length;
-    }
-
     /**
      * Revoke the reused `events:handlers` worker session for (holder, app), if
      * one was ever minted. Best-effort: a lookup or revoke failure must not

src/backend/services/events/appSockets.integration.test.ts

@@ -224,7 +224,6 @@ describe('an app connection', () => {
             'subject',
             'ts',
             'uid',
-            'viaWorker',
         ]);
     });
 

src/backend/services/events/forwardQueue.ts

@@ -81,8 +81,6 @@ export interface ForwardEvent {
     ownerUserId: number;
     /** Who caused it, so `self` is right on the far side. */
     actingUserId?: number;
-    /** Made by server-side code, so `viaWorker` is right on the far side. */
-    viaWorker?: true;
     /** The emitter's event id and timestamp, kept so the two copies match. */
     id: string;
     ts: number;

src/backend/services/events/forwarding.test.ts

@@ -2044,34 +2044,6 @@ describe('a kv value crossing to another region', () => {
 
         expect(eventsIn(west)[0].kv).toMatchObject({ value: { items: 3 } });
     });
-
-    it('carries who wrote it, so `self` and `viaWorker` hold on the far side', async () => {
-        const west = makeRegion('west', ['east'], forwardCfg);
-        const east = makeRegion('east', ['west'], forwardCfg);
-        await subscribeKv(east, 'socket-writer');
-        await announced(east);
-
-        await west.events.dispatchKv(
-            {
-                userId,
-                namespace: `v1:user-${userId}:${APP}`,
-                keys: ['cart'],
-                op: 'set',
-            },
-            { actingUserId: userId + 1, viaWorker: true },
-        );
-        await posted(west);
-        await arrived(east);
-
-        expect(eventsIn(west)[0]).toMatchObject({
-            actingUserId: userId + 1,
-            viaWorker: true,
-        });
-        expect(east.sent[0].event).toMatchObject({
-            self: false,
-            viaWorker: true,
-        });
-    });
 });
 
 describe('a session subscription in another region', () => {
@@ -2086,33 +2058,10 @@ describe('a session subscription in another region', () => {
         await dispatch(west);
 
         await arrived(east);
-        expect(east.sent[0].event).toMatchObject({
-            op: 'write',
-            self: true,
-            viaWorker: false,
-        });
+        expect(east.sent[0].event).toMatchObject({ op: 'write', self: true });
         expect(west.sent).toEqual([]);
     });
 
-    it('carries a server-side write as one on the far side', async () => {
-        const west = makeRegion('west', ['east'], forwardCfg);
-        const east = makeRegion('east', ['west'], forwardCfg);
-        await subscribeSession(east);
-        await posted(east);
-
-        await west.events.dispatchFs('fs.write.file', entry(), {
-            actingUserId: userId,
-            viaWorker: true,
-            ancestors: async () => ancestors(),
-        });
-
-        await arrived(east);
-        expect(east.sent[0].event).toMatchObject({
-            self: true,
-            viaWorker: true,
-        });
-    });
-
     it('delivers to a subscriber who is not the writer', async () => {
         const west = makeRegion('west', ['east'], forwardCfg);
         const east = makeRegion('east', ['west'], forwardCfg);

src/backend/services/events/kvHandleDelegation.integration.test.ts

@@ -42,10 +42,7 @@ import { runWithContext } from '../../core/context.js';
 import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
 import type { IConfig } from '../../types.js';
 import type { DeliveryEnvelope } from './EventsService.js';
-import {
-    kvShareManagePermission,
-    kvSharePermission,
-} from '../kvShare/kvShares.js';
+import { kvShareManagePermission, kvSharePermission } from './kvShares.js';
 
 const BOOT_TIMEOUT_MS = 120_000;
 const SOCKET_ID = 'kv-delegate-socket';
@@ -67,7 +64,6 @@ let appId: number;
 let appActor: Actor;
 
 const events = () => env.server.services.events;
-const shares = () => env.server.services.kvShare;
 const permissions = () => env.server.services.permission;
 
 const settled = (count = 1) =>
@@ -115,15 +111,11 @@ const undelegate = (prefix = PREFIX) =>
     );
 
 const mint = (request: Record<string, unknown> = {}, actor = appActor) =>
-    shares().mintKvHandle(
-        actor,
-        {
-            prefix: PREFIX,
-            ...request,
-            recipient: { username: guest.username },
-        },
-        { defaultAccess: 'watch' },
-    );
+    events().mintKvHandle(actor, {
+        granteeUsername: guest.username,
+        prefix: PREFIX,
+        ...request,
+    });
 
 const clearRows = async () => {
     await env.server.clients.db.write(`DELETE FROM \`${TABLE}\``, []);
@@ -199,7 +191,7 @@ describe('an app minting without consent', () => {
             legacyCode: 'events_kv_handle_not_delegated',
         });
         // The share itself is untouched: what was refused is the app asking.
-        const page = await shares().listKvHandles(owner.actor, { limit: 100 });
+        const page = await events().listKvHandles(owner.actor, { limit: 100 });
         expect(page.items).toContainEqual(
             expect.objectContaining({ handle, revokedAt: null }),
         );
@@ -413,14 +405,14 @@ describe('an app minting with consent', () => {
 
     it('shows up in the owner`s listing of what they have shared out', async () => {
         const { handle } = await mint();
-        const page = await shares().listKvHandles(owner.actor, { limit: 100 });
+        const page = await events().listKvHandles(owner.actor, { limit: 100 });
 
         expect(page.items).toContainEqual(
             expect.objectContaining({
                 handle,
                 prefix: PREFIX,
                 appUid,
-                holderUsername: guest.username,
+                granteeUsername: guest.username,
                 revokedAt: null,
             }),
         );
@@ -462,7 +454,7 @@ describe('a handle an app minted', () => {
             handlerName: 'onChange',
         });
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
         await vi.waitFor(
             async () => {
                 const [row] = (await env.server.clients.db.pread(
@@ -548,7 +540,7 @@ describe('a grantee subscribing through their own app actor', () => {
         await settled();
         expect(delivered[0].subId).toBe(sub.subId);
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
         delivered.length = 0;
 
         await appWrites(`${PREFIX}live:2`, 2);
@@ -581,7 +573,7 @@ describe('an app managing what it minted', () => {
             handlerName: 'onChange',
         });
 
-        await shares().revokeKvHandle(appActor, handle);
+        await events().revokeKvHandle(appActor, handle);
         await vi.waitFor(
             async () => {
                 const [row] = (await env.server.clients.db.pread(
@@ -600,7 +592,7 @@ describe('an app managing what it minted', () => {
             ),
         ).resolves.toBe(false);
 
-        const page = await shares().listKvHandles(owner.actor, { limit: 100 });
+        const page = await events().listKvHandles(owner.actor, { limit: 100 });
         expect(
             page.items.find((one) => one.handle === handle)?.revokedAt,
         ).toBeTypeOf('number');
@@ -615,10 +607,10 @@ describe('an app managing what it minted', () => {
         const prefix = `${PREFIX}session-in-app-${uuidv4().slice(0, 8)}:`;
         const { handle } = await mint({ appUid, prefix }, owner.actor);
 
-        const revoked = await shares().revokeKvHandle(appActor, handle);
+        const revoked = await events().revokeKvHandle(appActor, handle);
         expect(revoked.handle).toBe(handle);
 
-        const page = await shares().listKvHandles(owner.actor, { limit: 100 });
+        const page = await events().listKvHandles(owner.actor, { limit: 100 });
         expect(
             page.items.find((one) => one.handle === handle)?.revokedAt,
         ).toBeTypeOf('number');
@@ -632,7 +624,7 @@ describe('an app managing what it minted', () => {
         );
 
         await expect(
-            shares().revokeKvHandle(appActor, handle),
+            events().revokeKvHandle(appActor, handle),
         ).rejects.toMatchObject({ legacyCode: 'events_kv_handle_owner_only' });
     });
 
@@ -655,7 +647,7 @@ describe('an app managing what it minted', () => {
         });
 
         await expect(
-            shares().revokeKvHandle(siblingActor, handle),
+            events().revokeKvHandle(siblingActor, handle),
         ).rejects.toMatchObject({ legacyCode: 'events_kv_handle_owner_only' });
     });
 
@@ -673,7 +665,7 @@ describe('an app managing what it minted', () => {
         });
 
         await expect(
-            shares().revokeKvHandle(tokenActor, handle),
+            events().revokeKvHandle(tokenActor, handle),
         ).rejects.toMatchObject({ legacyCode: 'events_kv_handle_owner_only' });
     });
 
@@ -687,12 +679,12 @@ describe('an app managing what it minted', () => {
         await undelegate(prefix);
 
         await expect(
-            shares().revokeKvHandle(appActor, handle),
+            events().revokeKvHandle(appActor, handle),
         ).rejects.toMatchObject({
             legacyCode: 'events_kv_handle_not_delegated',
         });
 
-        const page = await shares().listKvHandles(owner.actor, {
+        const page = await events().listKvHandles(owner.actor, {
             limit: 100,
         });
         expect(
@@ -706,7 +698,7 @@ describe('an app managing what it minted', () => {
         await mint({ appUid: 'os-global', prefix: sessionPrefix }, owner.actor);
         await mint({ prefix: appPrefix });
 
-        const appPage = await shares().listKvHandles(appActor, {
+        const appPage = await events().listKvHandles(appActor, {
             limit: 100,
             includeTotal: true,
         });
@@ -716,7 +708,7 @@ describe('an app managing what it minted', () => {
             false,
         );
 
-        const ownerPage = await shares().listKvHandles(owner.actor, {
+        const ownerPage = await events().listKvHandles(owner.actor, {
             limit: 100,
             includeTotal: true,
         });
@@ -729,7 +721,7 @@ describe('an app managing what it minted', () => {
         const key = `rate:${EVENTS_KV_HANDLE_LIMIT.scope}:${owner.id}`;
 
         const before = await env.server.clients.redis.zcard(key);
-        await shares().revokeKvHandle(appActor, handle);
+        await events().revokeKvHandle(appActor, handle);
         const after = await env.server.clients.redis.zcard(key);
 
         expect(after).toBe(before + 1);
@@ -737,14 +729,14 @@ describe('an app managing what it minted', () => {
 
     it('answers another user`s handle in the same namespace as absent, not as forbidden', async () => {
         const prefix = `cross-user-${uuidv4().slice(0, 8)}:`;
-        const { handle } = await shares().mintKvHandle(
-            guest.actor,
-            { recipient: { username: owner.username }, appUid, prefix },
-            { defaultAccess: 'watch' },
-        );
+        const { handle } = await events().mintKvHandle(guest.actor, {
+            granteeUsername: owner.username,
+            appUid,
+            prefix,
+        });
 
         await expect(
-            shares().revokeKvHandle(appActor, handle),
+            events().revokeKvHandle(appActor, handle),
         ).rejects.toMatchObject({ legacyCode: 'subject_does_not_exist' });
     });
 
@@ -752,7 +744,7 @@ describe('an app managing what it minted', () => {
         const prefix = `${PREFIX}revoke-audit-probe-${uuidv4().slice(0, 8)}:`;
         const { handle } = await mint({ prefix });
 
-        await shares().revokeKvHandle(appActor, handle);
+        await events().revokeKvHandle(appActor, handle);
 
         const row = await vi.waitFor(async () => {
             const [found] = (await env.server.clients.db.pread(

src/backend/services/events/kvHandleRevoke.integration.test.ts

@@ -60,7 +60,6 @@ let stranger: TestUser;
 let delivered: DeliveryEnvelope[];
 
 const events = () => env.server.services.events;
-const shares = () => env.server.services.kvShare;
 
 const settled = (count = 1) =>
     vi.waitFor(() => expect(delivered.length).toBeGreaterThanOrEqual(count), {
@@ -89,11 +88,10 @@ const ownerWrites = (key: string, value: unknown): Promise<unknown> =>
     );
 
 const mint = (prefix = PREFIX) =>
-    shares().mintKvHandle(
-        owner.actor,
-        { prefix, recipient: { username: guest.username } },
-        { defaultAccess: 'watch' },
-    );
+    events().mintKvHandle(owner.actor, {
+        granteeUsername: guest.username,
+        prefix,
+    });
 
 /** A durable `single` row, which is the only kind that holds a backlog. */
 const subscribeDurable = async (handle: string) =>
@@ -184,7 +182,7 @@ describe('revoking a handle', () => {
         );
         expect(await ownerWatches()).toBe(true);
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
         await suspendedRow(sub.subId);
 
         // The anchor leaves the *owner's* watched set, which is the keyspace a
@@ -213,7 +211,7 @@ describe('revoking a handle', () => {
         await settled();
         expect(delivered[0].subId).toBe(sub.subId);
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
         delivered.length = 0;
 
         await ownerWrites(`${PREFIX}live:2`, 2);
@@ -231,21 +229,16 @@ describe('revoking a handle', () => {
         const settle = vi.spyOn(events(), 'settleRevokedGrant');
 
         try {
-            await shares().revokeKvHandle(owner.actor, handle);
+            await events().revokeKvHandle(owner.actor, handle);
             await suspendedRow(sub.subId);
 
-            // One grant settle for the holder, and a retired-handle settle
-            // for each side, each a single indexed read of that user's rows —
-            // no lookup keyed on the handle anywhere.
+            // One announcement, one settle pass, one indexed read of the
+            // holder's rows — no lookup keyed on the handle anywhere.
             expect(settle).toHaveBeenCalledTimes(1);
-            expect(
-                byHolder.mock.calls.map(([userId]) => userId).sort(),
-            ).toEqual([guest.id, guest.id, owner.id].sort());
-            for (const call of byHolder.mock.calls)
-                expect(call.slice(1)).toEqual([
-                    null,
-                    { includeSuspended: true },
-                ]);
+            expect(byHolder).toHaveBeenCalledTimes(1);
+            expect(byHolder).toHaveBeenCalledWith(guest.id, null, {
+                includeSuspended: true,
+            });
         } finally {
             byHolder.mockRestore();
             settle.mockRestore();
@@ -257,7 +250,7 @@ describe('revoking a handle', () => {
         const { handle } = await mint();
         const deeper = await mint(`${PREFIX}messages:`);
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
 
         // The subtree goes with the region: a grant left underneath would keep
         // access to part of what was just taken back.
@@ -278,12 +271,12 @@ describe('revoking a handle', () => {
         const deeper = await mint(`${PREFIX}messages:`);
         expect((await countLive()).total).toBe(before.total + 2);
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
 
         // The deeper handle's grant died with the subtree revoke above (proven
         // by the sibling case), so its row reading live would disagree with
         // reality — both in the listing and in the slot it appears to hold.
-        const page = await shares().listKvHandles(owner.actor, {
+        const page = await events().listKvHandles(owner.actor, {
             limit: 100,
         });
         const deeperRow = page.items.find((one) => one.handle === deeper.handle);
@@ -296,9 +289,9 @@ describe('revoking a handle', () => {
         const { handle } = await mint();
         const sibling = await mint('workspace:other:');
 
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
 
-        const page = await shares().listKvHandles(owner.actor, {
+        const page = await events().listKvHandles(owner.actor, {
             limit: 100,
         });
         const siblingRow = page.items.find(
@@ -310,7 +303,7 @@ describe('revoking a handle', () => {
     it('lets a fresh handle over the same region work, and leaves the old one dead', async () => {
         await clearRows();
         const first = await mint();
-        await shares().revokeKvHandle(owner.actor, first.handle);
+        await events().revokeKvHandle(owner.actor, first.handle);
 
         const second = await mint();
         expect(second.handle).not.toBe(first.handle);
@@ -341,7 +334,7 @@ describe('revoking a handle', () => {
                 : owner.actor;
 
         await expect(
-            shares().revokeKvHandle(actor, handle),
+            events().revokeKvHandle(actor, handle),
         ).rejects.toMatchObject({
             legacyCode: 'subject_does_not_exist',
         });
@@ -352,8 +345,8 @@ describe('revoking a handle', () => {
         // between them leaves a retry to finish the job — which only works if
         // reaching a retired handle again succeeds.
         const { handle } = await mint();
-        const first = await shares().revokeKvHandle(owner.actor, handle);
-        const again = await shares().revokeKvHandle(owner.actor, handle);
+        const first = await events().revokeKvHandle(owner.actor, handle);
+        const again = await events().revokeKvHandle(owner.actor, handle);
         expect(again).toEqual(first);
     });
 
@@ -372,7 +365,7 @@ describe('revoking a handle', () => {
             .spyOn(store, 'retire')
             .mockRejectedValueOnce(new Error('write failed'));
         await expect(
-            shares().revokeKvHandle(owner.actor, handle),
+            events().revokeKvHandle(owner.actor, handle),
         ).rejects.toThrow('write failed');
         failing.mockRestore();
 
@@ -384,7 +377,7 @@ describe('revoking a handle', () => {
         expect(delivered).toEqual([]);
 
         // And the retry converges rather than answering "no such handle".
-        const revoked = await shares().revokeKvHandle(owner.actor, handle);
+        const revoked = await events().revokeKvHandle(owner.actor, handle);
         expect(revoked.handle).toBe(handle);
         expect(await retire(handle, owner.id)).toMatchObject({
             revokedAt: revoked.revokedAt,
@@ -405,7 +398,7 @@ describe('revoking a handle', () => {
         });
 
         await expect(
-            shares().revokeKvHandle(appActor, handle),
+            events().revokeKvHandle(appActor, handle),
         ).rejects.toMatchObject({
             legacyCode: 'events_kv_handle_owner_only',
         });
@@ -415,9 +408,9 @@ describe('revoking a handle', () => {
 describe('the owner`s handle listing', () => {
     it('shows what was shared, retired handles included', async () => {
         const { handle } = await mint();
-        await shares().revokeKvHandle(owner.actor, handle);
+        await events().revokeKvHandle(owner.actor, handle);
 
-        const page = await shares().listKvHandles(owner.actor, {
+        const page = await events().listKvHandles(owner.actor, {
             includeTotal: true,
         });
         const row = page.items.find((one) => one.handle === handle);
@@ -425,9 +418,7 @@ describe('the owner`s handle listing', () => {
         expect(row).toMatchObject({
             prefix: PREFIX,
             appUid: 'os-global',
-            holderUsername: guest.username,
-            access: 'watch',
-            revokedBy: 'owner',
+            granteeUsername: guest.username,
         });
         expect(row?.revokedAt).toBeTypeOf('number');
         expect(page.total).toBe(page.items.length + (page.cursor ? 1 : 0));
@@ -435,7 +426,7 @@ describe('the owner`s handle listing', () => {
 
     it('shows the grantee nothing of the owner`s', async () => {
         await mint();
-        const page = await shares().listKvHandles(guest.actor);
+        const page = await events().listKvHandles(guest.actor);
         expect(page.items).toEqual([]);
     });
 
@@ -443,11 +434,11 @@ describe('the owner`s handle listing', () => {
         await mint();
         await mint();
 
-        const first = await shares().listKvHandles(owner.actor, { limit: 1 });
+        const first = await events().listKvHandles(owner.actor, { limit: 1 });
         expect(first.items).toHaveLength(1);
         expect(first.cursor).toBeTypeOf('string');
 
-        const second = await shares().listKvHandles(owner.actor, {
+        const second = await events().listKvHandles(owner.actor, {
             limit: 1,
             cursor: first.cursor,
         });

src/backend/services/events/kvHandles.integration.test.ts

@@ -46,7 +46,7 @@ import {
 import type { IConfig } from '../../types.js';
 import { DEFAULT_FREE_SUBSCRIPTION } from '../metering/consts.js';
 import type { DeliveryEnvelope } from './EventsService.js';
-import { kvSharePermission } from '../kvShare/kvShares.js';
+import { kvSharePermission } from './kvShares.js';
 import { isKvHandleId, kvAnchorToken } from './subjects.js';
 
 const BOOT_TIMEOUT_MS = 120_000;
@@ -68,7 +68,6 @@ let stranger: TestUser;
 let delivered: DeliveryEnvelope[];
 
 const events = () => env.server.services.events;
-const shares = () => env.server.services.kvShare;
 
 const settled = (count = 1) =>
     vi.waitFor(() => expect(delivered.length).toBeGreaterThanOrEqual(count), {
@@ -98,34 +97,14 @@ const ownerWrites = (key: string, value: unknown): Promise<unknown> =>
     );
 
 const mint = (
-    {
-        granteeUsername = guest.username,
-        ...request
-    }: Record<string, unknown> = {},
+    request: Record<string, unknown> = {},
     actor: Actor = owner.actor,
 ) =>
-    shares().mintKvHandle(
-        actor,
-        {
-            prefix: PREFIX,
-            ...request,
-            recipient: { username: granteeUsername as string },
-        },
-        { defaultAccess: 'watch' },
-    );
-
-/** An app row under a fresh uid, since a share may only name an app that exists. */
-const registerApp = async (
-    on: PuterTestEnv = env,
-    ownerUserId: number = owner.id,
-): Promise<string> => {
-    const uid = `app-${uuidv4()}`;
-    await on.server.clients.db.write(
-        'INSERT INTO `apps` (`uid`, `name`, `title`, `index_url`, `owner_user_id`) VALUES (?, ?, ?, ?, ?)',
-        [uid, uid, uid, `https://${uid}.example/`, ownerUserId],
-    );
-    return uid;
-};
+    events().mintKvHandle(actor, {
+        granteeUsername: guest.username,
+        prefix: PREFIX,
+        ...request,
+    });
 
 const clearRows = async () => {
     await env.server.clients.db.write(`DELETE FROM \`${TABLE}\``, []);
@@ -169,12 +148,7 @@ describe('minting a handle', () => {
         const minted = await mint();
 
         expect(isKvHandleId(minted.handle)).toBe(true);
-        expect(minted).toMatchObject({
-            handle: minted.handle,
-            prefix: PREFIX,
-            access: 'watch',
-            holderUsername: guest.username,
-        });
+        expect(minted).toEqual({ handle: minted.handle, prefix: PREFIX });
         const wire = JSON.stringify(minted);
         expect(wire).not.toContain(owner.uuid);
         expect(wire).not.toContain(owner.username);
@@ -325,8 +299,7 @@ describe('minting a handle', () => {
     });
 
     it('lets a paid namespace fill the account cap and then refuses other namespaces', async () => {
-        const namespace = await registerApp();
-        const another = await registerApp();
+        const namespace = 'app-perapp-probe';
         try {
             for (let i = 0; i < EVENTS_KV_HANDLES_PER_APP.limit; i++) {
                 const prefix = `perapp:${i}:`;
@@ -345,20 +318,20 @@ describe('minting a handle', () => {
                 legacyCode: 'events_kv_handle_limit_reached',
             });
             await expect(
-                mint({ appUid: another, prefix: 'still:room:' }),
+                mint({ appUid: 'app-another-probe', prefix: 'still:room:' }),
             ).rejects.toMatchObject({
                 legacyCode: 'events_kv_handle_limit_reached',
             });
         } finally {
             await env.server.clients.db.write(
                 'DELETE FROM `kv_share_handles` WHERE `owner_user_id` = ? AND `app_uid` IN (?, ?)',
-                [owner.id, namespace, another],
+                [owner.id, namespace, 'app-another-probe'],
             );
         }
     });
 
     it('hands back an existing handle at the cap, taking no slot', async () => {
-        const namespace = await registerApp();
+        const namespace = 'app-idempotent-probe';
         const prefix = 'idempotent:cap:';
         try {
             const first = await mint({ appUid: namespace, prefix });
@@ -776,7 +749,7 @@ describe('what a plan lets an account hold', () => {
 
     it('holds a free account to the free per-app cap, with room left in the account cap', async () => {
         await setEmail(`${tiered.users.user.username}@example.invalid`);
-        const namespace = await registerApp(tiered, tieredUserId);
+        const namespace = 'app-tiered-free-probe';
         const cap =
             EVENTS_KV_HANDLES_PER_APP.bySubscription[DEFAULT_FREE_SUBSCRIPTION];
         const grantee = await tiered.server.stores.user.getByUsername(
@@ -810,7 +783,7 @@ describe('what a plan lets an account hold', () => {
         // another namespace still succeeds.
         const accepted = await mintTiered(
             'still:room:',
-            await registerApp(tiered, tieredUserId),
+            'app-tiered-free-other',
         );
         expect(accepted.status).toBe(200);
     });

src/backend/services/events/kvShares.test.ts

@@ -0,0 +1,451 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { describe, expect, it, vi } from 'vitest';
+import type { Actor } from '../../core/actor.js';
+import { HttpError } from '../../core/http/HttpError.js';
+import { PermissionUtil } from '../permission/permissionUtil.js';
+import {
+    assertBoundedManageGrant,
+    assertShareableAppUid,
+    assertShareablePermission,
+    assertShareablePrefix,
+    keyPrefixSegments,
+    kvShareAppDelegateImplicator,
+    kvShareGrantCovers,
+    kvShareManagePermission,
+    kvShareOwnerImplicator,
+    kvSharePermission,
+    mintKvHandleId,
+    normalizeKeyPrefix,
+    relativeToKvShareRoot,
+} from './kvShares.js';
+import { isKvHandleId, kvHandleFromSubject } from './subjects.js';
+
+const OWNER = '2a1b0c9d-0000-4000-8000-000000000001';
+const OTHER = '2a1b0c9d-0000-4000-8000-000000000002';
+const APP = 'app-1234';
+const OTHER_APP = 'app-5678';
+
+const userActor = (uuid: string): Actor =>
+    ({ user: { uuid }, effectiveApp: null }) as unknown as Actor;
+
+const appActor = (uuid: string, appUid: string): Actor =>
+    ({
+        user: { uuid },
+        app: { uid: appUid },
+        effectiveApp: { uid: appUid },
+    }) as unknown as Actor;
+
+describe('the share permission family', () => {
+    it('names the owner, the app and the granted prefix', () => {
+        expect(kvSharePermission(OWNER, APP, 'workspace:abc:')).toBe(
+            `kv-share:${OWNER}:${APP}:workspace:abc`,
+        );
+    });
+
+    it('makes key segments components, so a deeper key is a descendant', () => {
+        const granted = kvSharePermission(OWNER, APP, 'workspace:abc:');
+        const deeper = kvSharePermission(
+            OWNER,
+            APP,
+            'workspace:abc:messages:1',
+        );
+
+        // The exploder walks parents of the string being checked, so implication
+        // over key segments needs nothing of its own.
+        expect(deeper.startsWith(`${granted}:`)).toBe(true);
+    });
+
+    it('escapes a `:` inside a component rather than splitting on it', () => {
+        const permission = kvSharePermission(OWNER, 'app:odd', 'cart:');
+        expect(PermissionUtil.split(permission)).toEqual([
+            'kv-share',
+            OWNER,
+            'app:odd',
+            'cart',
+        ]);
+    });
+
+    it('reads a withdrawn grant as covering itself and everything under it', () => {
+        const granted = kvSharePermission(OWNER, APP, 'workspace:abc:');
+        expect(kvShareGrantCovers(granted, granted)).toBe(true);
+        expect(
+            kvShareGrantCovers(
+                granted,
+                kvSharePermission(OWNER, APP, 'workspace:abc:messages:'),
+            ),
+        ).toBe(true);
+        // A sibling that merely shares a text prefix is a different region.
+        expect(
+            kvShareGrantCovers(
+                granted,
+                kvSharePermission(OWNER, APP, 'workspace:abcdef:'),
+            ),
+        ).toBe(false);
+        expect(
+            kvShareGrantCovers(
+                granted,
+                kvSharePermission(OTHER, APP, 'workspace:abc:'),
+            ),
+        ).toBe(false);
+        // Coverage never crosses namespaces: the app uid is what keeps a
+        // revoke inside the one the handle was minted in.
+        expect(
+            kvShareGrantCovers(
+                granted,
+                kvSharePermission(OWNER, OTHER_APP, 'workspace:abc:messages:'),
+            ),
+        ).toBe(false);
+    });
+
+    it('never reads a withdrawn child as covering its own parent', () => {
+        // Revoking the deeper of two grants must not read as covering the
+        // shallower one — coverage only ever runs downward.
+        const child = kvSharePermission(OWNER, APP, 'workspace:abc:messages:');
+        const parent = kvSharePermission(OWNER, APP, 'workspace:abc:');
+        expect(kvShareGrantCovers(child, parent)).toBe(false);
+    });
+});
+
+describe('granted prefixes', () => {
+    it('always ends on the key delimiter', () => {
+        expect(normalizeKeyPrefix('workspace:abc')).toBe('workspace:abc:');
+        expect(normalizeKeyPrefix('workspace:abc:')).toBe('workspace:abc:');
+        expect(keyPrefixSegments('workspace:abc:')).toEqual([
+            'workspace',
+            'abc',
+        ]);
+    });
+
+    it.each([
+        ['', 'the whole namespace'],
+        [':', 'delimiters only'],
+        ['workspace:*', 'a pattern'],
+        ['workspace:a?c', 'a single-character pattern'],
+        // Normalizing would drop the empty segment and grant `a:b:` instead —
+        // a region other than the one asked for.
+        ['workspace::abc:', 'an empty key segment'],
+        [':workspace:abc:', 'a leading empty segment'],
+        // `escape_permission_component` leaves `\\` alone while escaping `:`,
+        // so the stored prefix and the permission string would disagree and
+        // the share would silently never fire.
+        ['work\\space:abc:', 'a backslash'],
+    ])('refuses %s (%s)', (prefix) => {
+        let thrown: unknown;
+        try {
+            assertShareablePrefix(prefix);
+        } catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeInstanceOf(HttpError);
+        expect((thrown as HttpError).legacyCode).toBe(
+            'invalid_kv_share_prefix',
+        );
+    });
+
+    it('refuses a region too deep to fit the grant column', () => {
+        const deep = kvSharePermission(OWNER, APP, 'a'.repeat(300));
+        expect(() => assertShareablePermission(deep)).toThrow(HttpError);
+        expect(
+            assertShareablePermission(
+                kvSharePermission(OWNER, APP, 'workspace:abc:'),
+            ),
+        ).toBeTypeOf('string');
+    });
+
+    it('keeps the trailing delimiter optional', () => {
+        expect(assertShareablePrefix('workspace:abc')).toBe('workspace:abc:');
+        expect(assertShareablePrefix('workspace:abc:')).toBe('workspace:abc:');
+    });
+});
+
+describe('granted namespaces', () => {
+    it('takes an app uid, and the app-less namespace', () => {
+        expect(assertShareableAppUid(APP)).toBe(APP);
+        expect(assertShareableAppUid('os-global')).toBe('os-global');
+    });
+
+    it('refuses one past the column it is stored in', () => {
+        // A longer one reaches the insert as a write the column cannot hold.
+        let thrown: unknown;
+        try {
+            assertShareableAppUid('a'.repeat(41));
+        } catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeInstanceOf(HttpError);
+        expect((thrown as HttpError).statusCode).toBe(400);
+    });
+
+    it('takes both shapes a real app uid comes in', () => {
+        // Minted (`app-<uuidv4>`) and derived from an origin (`app-<uuidv5>`)
+        // — 40 characters either way, which is the column exactly.
+        const minted = `app-${uuidv4()}`;
+        expect(assertShareableAppUid(minted)).toBe(minted);
+        expect(minted).toHaveLength(40);
+    });
+
+    it('refuses a handle, which shares the slot but is not a namespace', () => {
+        expect(() => assertShareableAppUid(mintKvHandleId())).toThrow(
+            HttpError,
+        );
+    });
+
+    it('refuses anything else short enough to fit the column', () => {
+        // The slot ends up in a subject and in a permission string, so a
+        // namespace carrying a delimiter of either grammar is refused before
+        // it can be composed into one.
+        for (const uid of [
+            'os-globals',
+            'workspace:abc',
+            'app',
+            'app-',
+            'app-a:b',
+            'app-a#b',
+            'v1:someone:app-x',
+            '',
+        ])
+            expect(() => assertShareableAppUid(uid)).toThrow(HttpError);
+    });
+});
+
+describe('keys inside a granted region', () => {
+    const permission = kvSharePermission(OWNER, APP, 'workspace:abc:');
+
+    it('are named relative to the granted root', () => {
+        expect(
+            relativeToKvShareRoot(permission, 'workspace:abc:messages:1'),
+        ).toBe('messages:1');
+    });
+
+    it('read as outside when they are', () => {
+        expect(
+            relativeToKvShareRoot(permission, 'workspace:abcdef:x'),
+        ).toBeNull();
+        expect(relativeToKvShareRoot(permission, 'workspace:abc')).toBeNull();
+    });
+});
+
+describe('a delegation request', () => {
+    const region = kvShareManagePermission(
+        kvSharePermission(OWNER, APP, 'workspace:abc:'),
+    );
+
+    it('is the manage arm of the grant it would let an app issue', () => {
+        expect(region).toBe(`manage:kv-share:${OWNER}:${APP}:workspace:abc`);
+        expect(assertBoundedManageGrant(region)).toBe(region);
+    });
+
+    it.each([
+        ['manage:kv-share', 'the family itself'],
+        [`manage:kv-share:${OWNER}`, 'an owner and no namespace'],
+        [`manage:kv-share:${OWNER}:${APP}`, 'a whole namespace'],
+    ])('refuses %s (%s)', (permission) => {
+        let thrown: unknown;
+        try {
+            assertBoundedManageGrant(permission);
+        } catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeInstanceOf(HttpError);
+        expect((thrown as HttpError).legacyCode).toBe(
+            'invalid_kv_share_prefix',
+        );
+    });
+
+    it('leaves permissions from other families alone', () => {
+        const unrelated = `manage:fs:${OWNER}:write`;
+        expect(assertBoundedManageGrant(unrelated)).toBe(unrelated);
+        // The read arm of this family is not a delegation, so it is not this
+        // check's to bound.
+        expect(assertBoundedManageGrant(`kv-share:${OWNER}:${APP}`)).toBeTypeOf(
+            'string',
+        );
+    });
+});
+
+describe('handle ids', () => {
+    it('are told apart from an app uid in the same slot', () => {
+        const handle = mintKvHandleId();
+        expect(isKvHandleId(handle)).toBe(true);
+        expect(isKvHandleId(APP)).toBe(false);
+        expect(isKvHandleId('kvh-')).toBe(false);
+    });
+
+    it('carry nothing about the owner', () => {
+        const handle = mintKvHandleId();
+        expect(handle).not.toContain(OWNER);
+        expect(mintKvHandleId()).not.toBe(handle);
+    });
+
+    it('are recoverable from the subject a row stored', () => {
+        const handle = mintKvHandleId();
+        expect(kvHandleFromSubject(`kv:${handle}:messages:*`)).toBe(handle);
+        expect(kvHandleFromSubject(`kv:${APP}:messages:*`)).toBeNull();
+        expect(kvHandleFromSubject(`fs:${handle}:write`)).toBeNull();
+    });
+});
+
+describe('the owner implicator', () => {
+    const implicator = kvShareOwnerImplicator();
+    const permission = kvSharePermission(OWNER, APP, 'workspace:abc:');
+
+    it('answers the share family and its manage arm', () => {
+        expect(implicator.matches(permission)).toBe(true);
+        expect(implicator.matches(`manage:${permission}`)).toBe(true);
+        expect(implicator.matches(`fs:${OWNER}:read`)).toBe(false);
+    });
+
+    it('holds for the owner named in the permission, and nobody else', () => {
+        expect(
+            implicator.check({ actor: userActor(OWNER), permission }),
+        ).toEqual({});
+        expect(
+            implicator.check({
+                actor: userActor(OWNER),
+                permission: `manage:${permission}`,
+            }),
+        ).toEqual({});
+        expect(
+            implicator.check({ actor: userActor(OTHER), permission }),
+        ).toBeUndefined();
+    });
+
+    it('reads the owner past a `manage` key segment', () => {
+        // Stripping every `manage:` rather than the leading one would rewrite
+        // the string the owner is read out of.
+        const nested = kvSharePermission(OWNER, APP, 'manage:secrets:');
+        expect(implicator.matches(nested)).toBe(true);
+        expect(
+            implicator.check({ actor: userActor(OWNER), permission: nested }),
+        ).toEqual({});
+        expect(
+            implicator.check({ actor: userActor(OTHER), permission: nested }),
+        ).toBeUndefined();
+    });
+
+    it('never answers for an app or a token acting through the owner', () => {
+        const appActor = {
+            user: { uuid: OWNER },
+            app: { uid: APP },
+        } as unknown as Actor;
+        expect(
+            implicator.check({ actor: appActor, permission }),
+        ).toBeUndefined();
+    });
+});
+
+describe('the app delegate implicator', () => {
+    const permission = kvSharePermission(OWNER, APP, 'workspace:abc:');
+
+    it('answers the share family, never its manage arm, nor other families', () => {
+        const implicator = kvShareAppDelegateImplicator({
+            userHolds: vi.fn(),
+        });
+        expect(implicator.matches(permission)).toBe(true);
+        expect(implicator.matches(`manage:${permission}`)).toBe(false);
+        expect(implicator.matches(`fs:${OWNER}:read`)).toBe(false);
+    });
+
+    it("grants when the actor's own app matches the namespace app and the user holds the grant", async () => {
+        const userHolds = vi.fn().mockResolvedValue(true);
+        const implicator = kvShareAppDelegateImplicator({ userHolds });
+        const actor = appActor(OWNER, APP);
+
+        await expect(implicator.check({ actor, permission })).resolves.toEqual(
+            {},
+        );
+
+        expect(userHolds).toHaveBeenCalledTimes(1);
+        const [calledActor, calledPermission] = userHolds.mock.calls[0];
+        expect(calledActor.app).toBeUndefined();
+        expect(calledActor.effectiveApp).toBeNull();
+        expect(calledActor.user).toEqual({ uuid: OWNER });
+        expect(calledPermission).toBe(permission);
+    });
+
+    it('refuses when the user does not hold the grant', async () => {
+        const implicator = kvShareAppDelegateImplicator({
+            userHolds: vi.fn().mockResolvedValue(false),
+        });
+        await expect(
+            implicator.check({ actor: appActor(OWNER, APP), permission }),
+        ).resolves.toBeUndefined();
+    });
+
+    it("refuses when the actor's app differs from the namespace app", async () => {
+        const userHolds = vi.fn().mockResolvedValue(true);
+        const implicator = kvShareAppDelegateImplicator({ userHolds });
+
+        await expect(
+            implicator.check({
+                actor: appActor(OWNER, OTHER_APP),
+                permission,
+            }),
+        ).resolves.toBeUndefined();
+        expect(userHolds).not.toHaveBeenCalled();
+    });
+
+    it('refuses a plain user actor with no app', async () => {
+        const userHolds = vi.fn().mockResolvedValue(true);
+        const implicator = kvShareAppDelegateImplicator({ userHolds });
+
+        await expect(
+            implicator.check({ actor: userActor(OWNER), permission }),
+        ).resolves.toBeUndefined();
+        expect(userHolds).not.toHaveBeenCalled();
+    });
+
+    it('refuses an access-token actor', async () => {
+        const userHolds = vi.fn().mockResolvedValue(true);
+        const implicator = kvShareAppDelegateImplicator({ userHolds });
+        const actor = {
+            user: { uuid: OWNER },
+            app: { uid: APP },
+            accessToken: { uid: 't' },
+        } as unknown as Actor;
+
+        await expect(
+            implicator.check({ actor, permission }),
+        ).resolves.toBeUndefined();
+        expect(userHolds).not.toHaveBeenCalled();
+    });
+
+    it('refuses a permission with no key segments or no app', async () => {
+        const userHolds = vi.fn().mockResolvedValue(true);
+        const implicator = kvShareAppDelegateImplicator({ userHolds });
+        const actor = appActor(OWNER, APP);
+
+        await expect(
+            implicator.check({
+                actor,
+                permission: PermissionUtil.join('kv-share', OWNER, APP),
+            }),
+        ).resolves.toBeUndefined();
+        await expect(
+            implicator.check({
+                actor,
+                permission: PermissionUtil.join('kv-share', OWNER),
+            }),
+        ).resolves.toBeUndefined();
+        expect(userHolds).not.toHaveBeenCalled();
+    });
+});

src/backend/services/events/kvShares.ts

@@ -0,0 +1,327 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { randomUUID } from 'node:crypto';
+import {
+    type Actor,
+    isAppActor,
+    isPlainUserActor,
+    userRelatedActor,
+} from '../../core/actor.js';
+import { HttpError } from '../../core/http/HttpError.js';
+import { KV_SHARE_HANDLE_WIDTHS } from '../../stores/events/columnWidths.js';
+import { KV_GLOBAL_APP_KEY } from '../../stores/systemKv/SystemKVStore.js';
+import {
+    MANAGE_PERM_PREFIX,
+    PERMISSION_MAX_LEN,
+} from '../permission/consts.js';
+import type { PermissionImplicator } from '../permission/permissionUtil.js';
+import { PermissionUtil } from '../permission/permissionUtil.js';
+import {
+    isKvHandleId,
+    KV_HANDLE_PREFIX,
+    KV_KEY_SEPARATOR,
+} from './subjects.js';
+
+/**
+ * Letting one user watch a region of another's key-value namespace.
+ *
+ * The grant is an ordinary user-to-user permission, which is the whole point:
+ * `manage:` answers "may I delegate this", the exploder's prefix implication
+ * makes a grant on `workspace:abc:` answer every key beneath it, and revocation
+ * settling and the delivery re-check key off the stored string exactly as they
+ * do for a shared folder. Putting the ACL on the key-value item instead would
+ * take part in none of that, and would tax every write to the item besides.
+ *
+ * The permission names the owner, so its components are the three things a
+ * shared region is:
+ *
+ *     kv-share:<ownerUserUuid>:<appUid>:<keySegment>...
+ *
+ * Key segments are components rather than one escaped blob because that is what
+ * makes prefix implication work without a rule of its own: the check a deep key
+ * runs is a descendant of the grant string, and the existing parent walk finds
+ * it. The grantee never sees this string — the handle is the name on the wire.
+ */
+
+/** Root of the cross-user key-value share namespace. */
+export const KV_SHARE_PERMISSION_PREFIX = 'kv-share';
+
+/** Width of the `app_uid` column the handle row stores its namespace in. */
+export const KV_SHARE_APP_UID_MAX_LENGTH = KV_SHARE_HANDLE_WIDTHS.appUid.max;
+
+export const mintKvHandleId = (): string =>
+    `${KV_HANDLE_PREFIX}${randomUUID()}`;
+
+/** The key segments a prefix contributes to a permission string. */
+export const keyPrefixSegments = (keyPrefix: string): string[] =>
+    keyPrefix.split(KV_KEY_SEPARATOR).filter((segment) => segment.length > 0);
+
+/**
+ * A granted prefix as it is stored: always ending on the key delimiter, so
+ * `keyPrefix + relative` is a whole key and the region never accidentally
+ * includes the key that names it.
+ */
+export const normalizeKeyPrefix = (keyPrefix: string): string => {
+    const segments = keyPrefixSegments(keyPrefix);
+    return segments.length === 0
+        ? ''
+        : `${segments.join(KV_KEY_SEPARATOR)}${KV_KEY_SEPARATOR}`;
+};
+
+export const kvSharePermission = (
+    ownerUserUuid: string,
+    appUid: string,
+    keyPrefix: string,
+): string =>
+    PermissionUtil.join(
+        KV_SHARE_PERMISSION_PREFIX,
+        ownerUserUuid,
+        appUid,
+        ...keyPrefixSegments(keyPrefix),
+    );
+
+export const isKvSharePermission = (permission: string): boolean =>
+    permission === KV_SHARE_PERMISSION_PREFIX ||
+    permission.startsWith(`${KV_SHARE_PERMISSION_PREFIX}:`);
+
+/**
+ * Whether withdrawing `revoked` takes `held` with it. Prefix implication read
+ * backwards: a grant answers every check at or beneath it, so withdrawing it
+ * puts every one of those in question.
+ */
+export const kvShareGrantCovers = (revoked: string, held: string): boolean =>
+    held === revoked || held.startsWith(`${revoked}:`);
+
+/** The granted root a share grant names, read back as a key prefix. */
+export const kvShareGrantPrefix = (permission: string): string =>
+    normalizeKeyPrefix(
+        PermissionUtil.split(permission).slice(3).join(KV_KEY_SEPARATOR),
+    );
+
+/**
+ * A key inside a granted region, named the way its holder addresses it, or
+ * `null` for one outside. The handle is the granted root, so everything the
+ * holder is shown is relative to it — an absolute key would name a namespace
+ * they cannot address and were never told about.
+ */
+export const relativeToKvShareRoot = (
+    permission: string,
+    key: string,
+): string | null => {
+    const prefix = kvShareGrantPrefix(permission);
+    if (!prefix || !key.startsWith(prefix)) return null;
+    return key.slice(prefix.length);
+};
+
+// -- Minting input ----------------------------------------------------
+
+export const invalidPrefix = (message: string): HttpError =>
+    new HttpError(400, message, { legacyCode: 'invalid_kv_share_prefix' });
+
+export const invalidAppUid = (message: string): HttpError =>
+    new HttpError(400, message, { legacyCode: 'bad_request' });
+
+/**
+ * The region a handle may be minted on. A pattern is refused because a handle
+ * names a region rather than selecting within one, and the namespace root is
+ * refused because a handle over everything the app holds is not a bounded
+ * capability — it is the app's data, and sharing that is a different decision
+ * with a different consent.
+ */
+export const assertShareablePrefix = (keyPrefix: unknown): string => {
+    if (typeof keyPrefix !== 'string')
+        throw invalidPrefix('`prefix` must be a string');
+    if (keyPrefix.includes('*') || keyPrefix.includes('?'))
+        throw invalidPrefix('A share prefix is a key prefix, not a pattern');
+    // `escape_permission_component` escapes `:` as `\C` but leaves `\` alone,
+    // so a prefix carrying one desynchronizes the stored `key_prefix` from the
+    // permission string and the share silently never fires.
+    if (keyPrefix.includes('\\'))
+        throw invalidPrefix('A share prefix may not contain a backslash');
+    // Normalizing drops empty segments, so `a::b:` would silently become a
+    // grant on `a:b:` — a region other than the one asked for. Refused rather
+    // than rewritten; only the trailing delimiter is optional.
+    const written = keyPrefix.split(KV_KEY_SEPARATOR);
+    if (written[written.length - 1] === '') written.pop();
+    if (written.some((segment) => segment === ''))
+        throw invalidPrefix('A share prefix may not have an empty key segment');
+
+    const normalized = normalizeKeyPrefix(keyPrefix);
+    if (normalized === '')
+        throw invalidPrefix('A share prefix may not be the whole namespace');
+    return normalized;
+};
+
+/**
+ * The shape every app uid takes, minted or derived from an origin. Narrow on
+ * purpose: `:` and `#` delimit the anchor token and permission grammars, so
+ * excluding them matters as much as excluding the handle prefix does.
+ */
+const APP_UID_SHAPE = /^app-[A-Za-z0-9_-]{1,64}$/;
+
+/** Fixed namespaces with no app of their own. */
+const FIXED_KV_NAMESPACES: readonly string[] = [KV_GLOBAL_APP_KEY];
+
+/**
+ * The namespace a handle may be minted over: the caller's own app slot, or the
+ * app-less one. Bounded by the column that stores it, shaped like a real app
+ * uid or one of the platform's fixed namespaces, and never handle-shaped, since
+ * the two share the app slot of a `kv:` subject.
+ */
+export const assertShareableAppUid = (appUid: string): string => {
+    if (appUid.length > KV_SHARE_APP_UID_MAX_LENGTH)
+        throw invalidAppUid(
+            `\`appUid\` may not exceed ${KV_SHARE_APP_UID_MAX_LENGTH} characters`,
+        );
+    if (isKvHandleId(appUid))
+        throw invalidAppUid('A share handle does not name a namespace');
+    if (!APP_UID_SHAPE.test(appUid) && !FIXED_KV_NAMESPACES.includes(appUid))
+        throw invalidAppUid('`appUid` does not name a namespace');
+    return appUid;
+};
+
+/**
+ * The grant a mint would issue, refused when it would not fit the column every
+ * permission table declares. Key prefixes run to a kilobyte and permissions do
+ * not, so the real bound on how deep a region may be is this one.
+ */
+export const assertShareablePermission = (permission: string): string => {
+    if (permission.length > PERMISSION_MAX_LEN)
+        throw invalidPrefix(
+            `A share prefix must leave the grant under ${PERMISSION_MAX_LEN} characters`,
+        );
+    return permission;
+};
+
+// -- Delegation -------------------------------------------------------
+
+/** The delegation arm of a share grant: authority to hand the region out. */
+export const kvShareManagePermission = (permission: string): string =>
+    PermissionUtil.join(
+        MANAGE_PERM_PREFIX,
+        ...PermissionUtil.split(permission),
+    );
+
+export const KV_SHARE_MANAGE_PREFIX = `${MANAGE_PERM_PREFIX}:${KV_SHARE_PERMISSION_PREFIX}`;
+
+export const isKvShareManagePermission = (permission: string): boolean =>
+    permission === KV_SHARE_MANAGE_PREFIX ||
+    permission.startsWith(`${KV_SHARE_MANAGE_PREFIX}:`);
+
+/**
+ * A delegation must name a subtree. Consent on the namespace root reads as "let
+ * this app hand out anything it has stored for you", which is not a bounded
+ * capability and so is not something a prompt can put to a user.
+ */
+export const assertBoundedManageGrant = (permission: string): string => {
+    if (!isKvShareManagePermission(permission)) return permission;
+    const [, , owner, appUid, ...segments] = PermissionUtil.split(permission);
+    if (!owner || !appUid || segments.length === 0)
+        throw invalidPrefix(
+            'A share delegation must name a region, not the whole namespace',
+        );
+    return permission;
+};
+
+/**
+ * The unbounded `manage:` grant a bounded delegation's own permission descends
+ * from. The consent surface refuses to ever write this row, but
+ * `canManagePermission` walks ancestors to decide "may I delegate this", so if
+ * it exists by any other path it would silently authorize a mint anywhere in
+ * the namespace — this is what lets the mint path notice it regardless.
+ */
+export const kvShareManageNamespaceRoot = (permission: string): string => {
+    const [, owner, appUid] = PermissionUtil.split(permission);
+    return PermissionUtil.join(
+        MANAGE_PERM_PREFIX,
+        KV_SHARE_PERMISSION_PREFIX,
+        owner,
+        appUid,
+    );
+};
+
+// -- Permission rules -------------------------------------------------
+
+/**
+ * The permission a `manage:` arm delegates over. Only the leading component is
+ * stripped: a key segment may itself be `manage`, and taking those out would
+ * change which string the owner is read from.
+ */
+const withoutManageArm = (permission: string): string =>
+    permission.startsWith(`${MANAGE_PERM_PREFIX}:`)
+        ? permission.slice(MANAGE_PERM_PREFIX.length + 1)
+        : permission;
+
+/**
+ * Owning the namespace is holding every share grant over it, and being able to
+ * issue them. Without this the owner cannot mint a handle on their own data:
+ * `grantUserUserPermission` asks `canManagePermission` first, and there is no
+ * row anywhere saying a user may manage what is already theirs.
+ *
+ * Restricted to plain user actors, as the filesystem's `is-owner` is. An app
+ * disposing of a region of its user's namespace is delegation, which is the
+ * `manage:` grant's job rather than this one's.
+ */
+export const kvShareOwnerImplicator = (): PermissionImplicator => ({
+    id: 'kv-share-is-owner',
+    shortcut: true,
+    matches: (permission: string): boolean =>
+        isKvSharePermission(withoutManageArm(permission)),
+    check: ({ actor, permission }): unknown => {
+        if (!isPlainUserActor(actor)) return undefined;
+        const uuid = actor.user?.uuid;
+        if (!uuid) return undefined;
+
+        const owner = PermissionUtil.split(withoutManageArm(permission))[1];
+        return owner === uuid ? {} : undefined;
+    },
+});
+
+/**
+ * Letting an app-under-user actor exercise a `kv-share:` grant its user holds,
+ * bounded to the app the grant's namespace names.
+ *
+ * Only the read arm is matched — never `manage:kv-share:…` — because answering
+ * the manage arm here would read as the unbounded namespace-root delegation and
+ * break minting for everyone (see `kvShareManageNamespaceRoot`). The
+ * namespace-app check keeps one app from reading a region shared with another
+ * app of the same user.
+ */
+export const kvShareAppDelegateImplicator = (deps: {
+    userHolds: (actor: Actor, permission: string) => Promise<boolean>;
+}): PermissionImplicator => ({
+    id: 'kv-share-app-delegate',
+    shortcut: true,
+    matches: (permission: string): boolean => isKvSharePermission(permission),
+    check: async ({ actor, permission }): Promise<unknown> => {
+        if (!isAppActor(actor)) return undefined;
+        const app = actor.effectiveApp;
+        if (!app?.uid) return undefined;
+
+        const [, owner, namespaceApp, ...segments] =
+            PermissionUtil.split(permission);
+        if (!owner || !namespaceApp || segments.length === 0) return undefined;
+        if (namespaceApp !== app.uid) return undefined;
+
+        return (await deps.userHolds(userRelatedActor(actor), permission))
+            ? {}
+            : undefined;
+    },
+});

src/backend/services/events/registry.test.ts

@@ -43,20 +43,10 @@ const PROJECTED_KEYS = [
     'subject',
     'ts',
     'uid',
-    'viaWorker',
 ];
 
 /** A KV event names a key where an FS event names a node. */
-const PROJECTED_KV_KEYS = [
-    'id',
-    'key',
-    'op',
-    'self',
-    'seq',
-    'subject',
-    'ts',
-    'viaWorker',
-];
+const PROJECTED_KV_KEYS = ['id', 'key', 'op', 'self', 'seq', 'subject', 'ts'];
 
 const entry = {
     id: 42,
@@ -205,24 +195,11 @@ describe('the kv subject', () => {
             op: 'set',
             key: 'cart:items',
             self: true,
-            viaWorker: false,
             ts: 1_700_000_002,
             seq: 0,
         });
     });
 
-    it('says whether server-side code made the change, on kv and fs alike', () => {
-        expect(
-            subject().project({ ...kvDelivery, viaWorker: true }),
-        ).toMatchObject({ viaWorker: true });
-        expect(
-            lookupFsSubject('fs.write.file')!.project({
-                ...delivery,
-                viaWorker: true,
-            }),
-        ).toMatchObject({ viaWorker: true });
-    });
-
     it('names the namespace app, never the namespace itself', () => {
         const projected = subject().project(kvDelivery) as Record<
             string,

src/backend/services/events/registry.ts

@@ -64,11 +64,6 @@ export interface ProjectedFsEvent extends ProjectedEventBase {
     path: string;
     /** Present only on a `move` a subscribed folder lost the node from. */
     from?: string;
-    /**
-     * The change was made by server-side code running as the account (a worker,
-     * or an events handler) rather than by the account directly.
-     */
-    viaWorker: boolean;
 }
 
 /**
@@ -85,8 +80,6 @@ export interface ProjectedKvEvent extends ProjectedEventBase {
      * value is small enough to inline; an `expire` never carries one.
      */
     value?: unknown;
-    /** See {@link ProjectedFsEvent.viaWorker}. */
-    viaWorker: boolean;
 }
 
 /**
@@ -149,8 +142,6 @@ export interface EventContextBase {
     ts: number;
     /** Handler runs behind the change. Never projected. */
     handlerDepth?: number;
-    /** Made by server-side code running as the account; see `viaWorkerOf`. */
-    viaWorker?: boolean;
 }
 
 /** What dispatch knows about one committed filesystem change. */
@@ -293,7 +284,6 @@ const fsProject =
         path: delivery.entry.path,
         ...(delivery.movedFrom ? { from: delivery.movedFrom.path } : {}),
         self: delivery.self,
-        viaWorker: delivery.viaWorker === true,
         ts: delivery.ts,
         seq: delivery.seq,
     });
@@ -319,7 +309,6 @@ const kvProject = (delivery: KvDeliveryContext): ProjectedKvEvent => ({
     key: delivery.kvKey,
     ...(delivery.value !== undefined ? { value: delivery.value } : {}),
     self: delivery.self,
-    viaWorker: delivery.viaWorker === true,
     ts: delivery.ts,
     seq: delivery.seq,
 });
@@ -440,10 +429,6 @@ export const UNPUBLISHED_INTERNAL_EVENTS = [
         event: 'kv.flushed',
         reason: 'No subject addresses "the whole namespace went": the grammar anchors on a key or a prefix, and fanning a flush out per key would report keys a truncated enumeration never saw.',
     },
-    {
-        event: 'kv.share.retired',
-        reason: 'A share handle stopping is not a change to any key; it ends the subscriptions made through the handle rather than being delivered to them.',
-    },
 ] as const satisfies readonly UnpublishedInternalEvent[];
 
 // Every `fs.*`/`kv.*`/`notif.*` bus key needs a decision. A new key that is in

src/backend/services/events/subjects.ts

@@ -194,10 +194,6 @@ export const notifMatchOn = (
     audience: NotificationAudience | string,
 ): string => `${ref}${NOTIF_MATCH_SEPARATOR}${audience}`;
 
-/** Whether a notif filter spans every app: a session's generic slice. */
-export const notifMatchSpansEveryApp = (match: string | null): boolean =>
-    match?.startsWith(`*${NOTIF_MATCH_SEPARATOR}`) === true;
-
 /** Which family a stored row belongs to, without re-parsing its subject. */
 export const isKvToken = (token: string): boolean =>
     token.startsWith(KV_TOKEN_PREFIX);

src/backend/services/events/workerInvoker.integration.test.ts

@@ -425,7 +425,6 @@ describe('the call an owed delivery makes', () => {
             'subject',
             'ts',
             'uid',
-            'viaWorker',
         ]);
         expect(call.body.event).toMatchObject({
             path: `${anchor}/note.txt`,

src/backend/services/fs/FSService.ts

@@ -41,7 +41,6 @@ import {
     isAccountContext,
     isAppActor,
     isPlainUserActor,
-    viaWorkerOf,
 } from '../../core/actor.js';
 import { Context } from '../../core/context.js';
 import { HttpError } from '../../core/http/HttpError.js';
@@ -4795,7 +4794,6 @@ export class FSService extends PuterService {
         const actor = Context.get('actor') as Actor | undefined;
         const actingUserId = actor?.user?.id;
         const handlerDepth = handlerDepthOf(actor);
-        const viaWorker = viaWorkerOf(actor);
         const movedFromChain = movedFrom && {
             path: movedFrom.path,
             ancestors: () => fsEntry.getAncestorChain(movedFrom.path),
@@ -4809,7 +4807,6 @@ export class FSService extends PuterService {
                         events.dispatchFs(key, entry, {
                             actingUserId,
                             handlerDepth,
-                            viaWorker,
                             ancestors: () => ancestors(entry),
                             ...(movedFromChain
                                 ? { movedFrom: movedFromChain }

src/backend/services/index.ts

@@ -33,7 +33,6 @@ import { EventForwardService } from './events/EventForwardService';
 import { EventsService } from './events/EventsService';
 import { AppFeedbackService } from './feedback/AppFeedbackService';
 import { FSService } from './fs/FSService';
-import { KvShareService } from './kvShare/KvShareService';
 import { ServerHealthService } from './health/ServerHealthService';
 import { PuterHomepageService } from './homepage/PuterHomepageService';
 import { LocalWorkerService } from './localworker/LocalWorkerService';
@@ -75,7 +74,6 @@ declare module './types' {
         suggestedApps: SuggestedAppsService;
         app: AppService;
         socket: SocketService;
-        kvShare: KvShareService;
         events: EventsService;
         eventForward: EventForwardService;
         notification: NotificationService;
@@ -136,9 +134,6 @@ export const puterServices = {
     // Reaches `auth` and `permission` at call time only.
     app: AppService,
     socket: SocketService,
-    // Registers the share-grant implicators with `permission`, and reaches
-    // `permission`, `metering` and `notification` at call time only.
-    kvShare: KvShareService,
     // Delivers through `socket` and resolves paths through `fs`, so it follows
     // both; `fs` reaches back for dispatch at call time only.
     events: EventsService,

src/backend/services/kvShare/kvShareConsistency.integration.test.ts

@@ -1,365 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-/**
- * Withdrawing a share against a replica that lags the primary, and the MySQL
- * matching rules a share's grants and rows meet. Runs on SQLite, and also on
- * MySQL when `PUTER_TEST_MYSQL_PORT` names one.
- */
-
-import { fileURLToPath } from 'node:url';
-import mysql from 'mysql2/promise';
-import { v4 as uuidv4 } from 'uuid';
-import {
-    afterAll,
-    beforeAll,
-    beforeEach,
-    describe,
-    expect,
-    it,
-    vi,
-} from 'vitest';
-import { EVENTS_KV_HANDLE_LIMIT } from '../../controllers/events/limits.js';
-import { makeActor, type Actor } from '../../core/actor.js';
-import { runWithContext } from '../../core/context.js';
-import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
-import type { IConfig } from '../../types.js';
-import {
-    kvShareGrantAtEveryLevel,
-    kvSharePermission,
-    type KvShareAccess,
-} from './kvShares.js';
-
-const BOOT_TIMEOUT_MS = 300_000;
-const GLOBAL = 'os-global';
-const MYSQL = {
-    host: '127.0.0.1',
-    port: Number(process.env.PUTER_TEST_MYSQL_PORT ?? 3307),
-    user: 'root',
-    password: 'puter',
-};
-const MIGRATIONS = fileURLToPath(
-    new URL('../../clients/database/migrations/mysql', import.meta.url),
-);
-const ENGINES = [
-    'sqlite',
-    ...(process.env.PUTER_TEST_MYSQL_PORT ? ['mysql'] : []),
-] as const;
-
-interface TestUser {
-    actor: Actor;
-    username: string;
-    id: number;
-    uuid: string;
-}
-
-describe.each(ENGINES)('key-value shares on %s', (engine) => {
-    const database = `kv_share_${Date.now().toString(36)}`;
-    let env: PuterTestEnv;
-    let owner: TestUser;
-    let guest: TestUser;
-
-    const db = () => env.server.clients.db;
-    const shares = () => env.server.services.kvShare;
-    const permissions = () => env.server.services.permission;
-    const handles = () => env.server.stores.kvShareHandle;
-    const flat = () => env.server.stores.permission;
-
-    const userFor = async (username: string): Promise<TestUser> => {
-        const row = await env.server.stores.user.getByUsername(username);
-        return {
-            actor: makeActor({ user: row as never }),
-            username,
-            id: row!.id,
-            uuid: row!.uuid as string,
-        };
-    };
-
-    const region = (label: string) => `${label}-${uuidv4().slice(0, 8)}:`;
-
-    const share = (prefix: string, access: KvShareAccess) =>
-        shares().mintKvHandle(
-            owner.actor,
-            { prefix, recipient: { username: guest.username }, access },
-            { defaultAccess: 'read' },
-        );
-
-    const grantRows = async (prefix: string) =>
-        (
-            await db().pread(
-                'SELECT `permission` FROM `user_to_user_permissions` ' +
-                    'WHERE `holder_user_id` = ? AND `permission` IN (?, ?, ?)',
-                [
-                    guest.id,
-                    ...kvShareGrantAtEveryLevel(
-                        kvSharePermission(owner.uuid, GLOBAL, prefix),
-                    ),
-                ],
-            )
-        ).map((row) => String(row.permission));
-
-    /**
-     * From here until the returned function runs, replica reads see the grant
-     * table as it is now and primary reads see it as it really is.
-     */
-    const lagReplica = async () => {
-        await db().write('DROP TABLE IF EXISTS `u2u_lagging`');
-        await db().write(
-            'CREATE TABLE `u2u_lagging` AS SELECT * FROM `user_to_user_permissions`',
-        );
-        const read = db().read.bind(db());
-        const replica = vi
-            .spyOn(db(), 'read')
-            .mockImplementation((query, params) =>
-                read(
-                    query.replaceAll(
-                        '`user_to_user_permissions`',
-                        '`u2u_lagging`',
-                    ),
-                    params,
-                ),
-            );
-        // SQLite's own primary read goes through `read`, so route it past the
-        // lagging view explicitly.
-        const primary = vi
-            .spyOn(db(), 'pread')
-            .mockImplementation((query, params) => read(query, params));
-        return async () => {
-            replica.mockRestore();
-            primary.mockRestore();
-            await db().write('DROP TABLE `u2u_lagging`');
-        };
-    };
-
-    /** No row, no flat entry, and no write reaching a later nested share. */
-    const expectWithdrawn = async (prefix: string) => {
-        expect(await grantRows(prefix)).toEqual([]);
-        expect(
-            await flat().getFlatUserPerms(
-                guest.id,
-                kvShareGrantAtEveryLevel(
-                    kvSharePermission(owner.uuid, GLOBAL, prefix),
-                ),
-            ),
-        ).toEqual([]);
-        const nested = await share(`${prefix}nested:`, 'watch');
-        await expect(
-            runWithContext({ actor: guest.actor }, () =>
-                env.server.drivers.kvStore.set({
-                    key: 'k',
-                    value: 1,
-                    optConfig: { handle: nested.handle },
-                }),
-            ),
-        ).rejects.toMatchObject({ legacyCode: 'kv_handle_access_denied' });
-    };
-
-    beforeAll(async () => {
-        const flags = {
-            events: { enabled: true, kvHandles: true },
-            kv: { shareHandles: true },
-            unlimitedMetering: true,
-        };
-        if (engine === 'mysql') {
-            const admin = await mysql.createConnection(MYSQL);
-            await admin.query(`CREATE DATABASE \`${database}\``);
-            await admin.end();
-            env = await setupPuterTestEnv({
-                ...flags,
-                database: {
-                    engine: 'mysql',
-                    ...MYSQL,
-                    database,
-                    migrationPaths: [MIGRATIONS],
-                },
-            } as never);
-        } else {
-            env = await setupPuterTestEnv(flags as IConfig);
-        }
-        owner = await userFor(env.users.user.username);
-        guest = await userFor(env.users.other.username);
-    }, BOOT_TIMEOUT_MS);
-
-    afterAll(async () => {
-        await env?.shutdown();
-        if (engine !== 'mysql') return;
-        const admin = await mysql.createConnection(MYSQL);
-        await admin.query(`DROP DATABASE IF EXISTS \`${database}\``);
-        await admin.end();
-    });
-
-    beforeEach(async () => {
-        for (const user of [owner, guest])
-            await env.server.clients.redis.del(
-                `rate:${EVENTS_KV_HANDLE_LIMIT.scope}:${user.id}`,
-            );
-    });
-
-    describe('an owner revoke while the replica lags', () => {
-        it('withdraws a share minted inside the lag', async () => {
-            const prefix = region('lag-mint');
-            const thaw = await lagReplica();
-            try {
-                const { handle } = await share(prefix, 'write');
-                await shares().removeKvShare(owner.actor, handle);
-            } finally {
-                await thaw();
-            }
-            await expectWithdrawn(prefix);
-        });
-
-        it('withdraws the write grant of a read share raised inside the lag', async () => {
-            const prefix = region('lag-raise');
-            const { handle } = await share(prefix, 'read');
-            const thaw = await lagReplica();
-            try {
-                await share(prefix, 'write');
-                await shares().removeKvShare(owner.actor, handle);
-            } finally {
-                await thaw();
-            }
-            await expectWithdrawn(prefix);
-        });
-
-        it('clears a flat entry under the region that no row backs', async () => {
-            const prefix = region('orphan');
-            const { handle } = await share(prefix, 'read');
-            const orphan = kvSharePermission(
-                owner.uuid,
-                GLOBAL,
-                `${prefix}deep:`,
-                'write',
-            );
-            await flat().setFlatUserPerm(guest.id, orphan, {
-                permission: orphan,
-                issuer_user_id: owner.id,
-                deleted: false,
-            });
-
-            await shares().removeKvShare(owner.actor, handle);
-
-            expect(await flat().getFlatUserPerms(guest.id, [orphan])).toEqual(
-                [],
-            );
-        });
-    });
-
-    describe('matching a share`s prefix', () => {
-        it('finds a live share by its exact bytes only', async () => {
-            const prefix = region('exact');
-            await share(prefix, 'read');
-            const input = {
-                ownerUserId: owner.id,
-                granteeUserId: guest.id,
-                appUid: GLOBAL,
-                keyPrefix: prefix,
-            };
-            expect(await handles().findLive(input)).not.toBeNull();
-            expect(
-                await handles().findLive({
-                    ...input,
-                    keyPrefix: prefix.toUpperCase(),
-                }),
-            ).toBeNull();
-        });
-
-        it.skipIf(engine !== 'mysql')(
-            'uses no operator MySQL warns is deprecated, whatever the connection charset',
-            async () => {
-                const pread = vi.spyOn(db(), 'pread');
-                let call: unknown[] | undefined;
-                try {
-                    await handles().findLive({
-                        ownerUserId: owner.id,
-                        granteeUserId: guest.id,
-                        appUid: GLOBAL,
-                        keyPrefix: region('warn'),
-                    });
-                    call = pread.mock.calls.find(([query]) =>
-                        query.includes('`key_prefix`'),
-                    );
-                } finally {
-                    pread.mockRestore();
-                }
-                expect(call).toBeDefined();
-
-                // The text protocol, so the statement is parsed (and warned
-                // about) as it runs.
-                const connection = await mysql.createConnection({
-                    ...MYSQL,
-                    database,
-                    charset: 'LATIN1_SWEDISH_CI',
-                });
-                try {
-                    await connection.query(
-                        String(call![0]),
-                        call![1] as never[],
-                    );
-                    const [warnings] = await connection.query('SHOW WARNINGS');
-                    expect(warnings).toEqual([]);
-                } finally {
-                    await connection.end();
-                }
-            },
-        );
-    });
-
-    describe('revoking a grant the database spells differently', () => {
-        it.skipIf(engine !== 'mysql')(
-            'clears the flat entry under the spelling it removed',
-            async () => {
-                const tag = uuidv4().slice(0, 8);
-                const stored = kvSharePermission(
-                    owner.uuid,
-                    GLOBAL,
-                    `Notes-${tag}:`,
-                    'read',
-                );
-                const asked = kvSharePermission(
-                    owner.uuid,
-                    GLOBAL,
-                    `notes-${tag}:`,
-                    'read',
-                );
-                await permissions().grantUserUserPermission(
-                    owner.actor,
-                    guest.username,
-                    stored,
-                );
-                expect(await permissions().check(guest.actor, stored)).toBe(
-                    true,
-                );
-
-                const removed = await permissions().revokeUserUserPermissions(
-                    owner.actor,
-                    guest.username,
-                    [asked],
-                );
-
-                expect(removed).toEqual([stored]);
-                expect(
-                    await flat().getFlatUserPerms(guest.id, [stored]),
-                ).toEqual([]);
-                expect(await permissions().check(guest.actor, stored)).toBe(
-                    false,
-                );
-            },
-        );
-    });
-});

src/backend/services/kvShare/kvShareRecipient.integration.test.ts

@@ -1,549 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-/**
- * What the recipient of a key-value share sees and controls: the notification
- * that tells their app a share arrived, kept off their desktop, and the share
- * blocks that refuse one.
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import {
-    afterAll,
-    beforeAll,
-    beforeEach,
-    describe,
-    expect,
-    it,
-    vi,
-} from 'vitest';
-import {
-    EVENTS_COALESCE_WINDOW_MS,
-    EVENTS_KV_HANDLE_LIMIT,
-    KV_SHARE_NOTICE_LIMIT,
-} from '../../controllers/events/limits.js';
-import { makeActor, type Actor } from '../../core/actor.js';
-import { runWithContext } from '../../core/context.js';
-import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
-import type { IConfig } from '../../types.js';
-import type { DeliveryEnvelope } from '../events/EventsService.js';
-import type { KvShareAccess } from './kvShares.js';
-
-const BOOT_TIMEOUT_MS = 120_000;
-
-interface TestUser {
-    actor: Actor;
-    username: string;
-    id: number;
-    uuid: string;
-}
-
-/** One server, its two users, and a fresh app the owner can share data of. */
-const bootEnv = (config: Record<string, unknown>) => {
-    const state = {
-        env: null as unknown as PuterTestEnv,
-        owner: null as unknown as TestUser,
-        guest: null as unknown as TestUser,
-    };
-
-    const userFor = async (username: string): Promise<TestUser> => {
-        const row = await state.env.server.stores.user.getByUsername(username);
-        return {
-            actor: makeActor({ user: row as never }),
-            username,
-            id: row!.id,
-            uuid: row!.uuid as string,
-        };
-    };
-
-    beforeAll(async () => {
-        state.env = await setupPuterTestEnv({
-            events: { enabled: true, kvHandles: true },
-            kv: { shareHandles: true },
-            unlimitedMetering: true,
-            ...config,
-        } as IConfig);
-        state.owner = await userFor(state.env.users.user.username);
-        state.guest = await userFor(state.env.users.other.username);
-    }, BOOT_TIMEOUT_MS);
-
-    afterAll(async () => {
-        await state.env?.shutdown();
-    });
-
-    beforeEach(async () => {
-        for (const user of [state.owner, state.guest])
-            await state.env.server.clients.redis.del(
-                `rate:${EVENTS_KV_HANDLE_LIMIT.scope}:${user.id}`,
-            );
-        await state.env.server.clients.redis.del(
-            `rate:${KV_SHARE_NOTICE_LIMIT.scope}:${state.owner.id}:${state.guest.id}`,
-        );
-    });
-
-    const makeApp = async () => {
-        const name = `kv-recipient-${uuidv4().slice(0, 8)}`;
-        return state.env.server.stores.app.create(
-            {
-                name,
-                title: 'Recipient App',
-                index_url: `https://${name}.example.test/index.html`,
-            },
-            { ownerUserId: state.owner.id },
-        );
-    };
-
-    const share = (
-        prefix: string,
-        access: KvShareAccess,
-        opts: { appUid?: string; label?: unknown } = {},
-    ) =>
-        state.env.server.services.kvShare.mintKvHandle(
-            state.owner.actor,
-            {
-                prefix,
-                recipient: { username: state.guest.username },
-                access,
-                ...(opts.appUid ? { appUid: opts.appUid } : {}),
-                ...(opts.label !== undefined ? { label: opts.label } : {}),
-            },
-            { defaultAccess: 'read' },
-        );
-
-    /** The holder's share notifications naming one handle. */
-    const notificationsFor = async (handle: string) =>
-        (
-            await state.env.server.clients.db.pread(
-                'SELECT `uid`, `app_uid`, `audience`, `value` FROM `notification` ' +
-                    "WHERE `user_id` = ? AND `type` = 'kv.share.received'",
-                [state.guest.id],
-            )
-        )
-            .map((row) => ({
-                uid: String(row.uid),
-                appUid: row.app_uid,
-                audience: row.audience,
-                value: (typeof row.value === 'string'
-                    ? JSON.parse(row.value)
-                    : row.value) as Record<string, unknown>,
-            }))
-            .filter((row) => row.value.handle === handle);
-
-    return { state, makeApp, share, notificationsFor };
-};
-
-const region = (label: string) => `${label}-${uuidv4().slice(0, 8)}:`;
-
-describe('the share notification', () => {
-    const { state, makeApp, share, notificationsFor } = bootEnv({});
-
-    it('reaches the holder once, in the app the data belongs to, without the owner', async () => {
-        const app = await makeApp();
-        const prefix = region('notify');
-        const shared = await share(prefix, 'write', {
-            appUid: app.uid,
-            label: 'Groceries',
-        });
-
-        const rows = await notificationsFor(shared.handle);
-        expect(rows).toHaveLength(1);
-        expect(rows[0]).toMatchObject({
-            appUid: app.uid,
-            audience: 'app-user',
-        });
-        expect(rows[0].value).toEqual({
-            type: 'kv.share.received',
-            handle: shared.handle,
-            access: 'write',
-            label: 'Groceries',
-            createdAt: shared.createdAt,
-        });
-        const wire = JSON.stringify(rows);
-        expect(wire).not.toContain(state.owner.uuid);
-        expect(wire).not.toContain(state.owner.username);
-        expect(wire).not.toContain(prefix);
-    });
-
-    it('is not sent again for a re-share, a level change or a label change', async () => {
-        const app = await makeApp();
-        const prefix = region('again');
-        const { handle } = await share(prefix, 'read', { appUid: app.uid });
-        await share(prefix, 'read', { appUid: app.uid });
-        await share(prefix, 'write', { appUid: app.uid });
-        await share(prefix, 'write', { appUid: app.uid, label: 'Renamed' });
-        expect(await notificationsFor(handle)).toHaveLength(1);
-    });
-
-    it('is sent at most five times an hour per owner and holder, and the share is made anyway', async () => {
-        const app = await makeApp();
-        const prefix = region('churn');
-        const handles: string[] = [];
-        for (let i = 0; i < KV_SHARE_NOTICE_LIMIT.limit + 2; i++) {
-            const { handle } = await share(prefix, 'read', { appUid: app.uid });
-            handles.push(handle);
-            await state.env.server.services.kvShare.removeKvShare(
-                state.owner.actor,
-                handle,
-            );
-        }
-        expect(new Set(handles).size).toBe(handles.length);
-        const counts = await Promise.all(
-            handles.map(
-                async (handle) => (await notificationsFor(handle)).length,
-            ),
-        );
-        expect(counts.reduce((sum, n) => sum + n, 0)).toBe(
-            KV_SHARE_NOTICE_LIMIT.limit,
-        );
-        expect(counts.slice(KV_SHARE_NOTICE_LIMIT.limit)).toEqual([0, 0]);
-    });
-
-    it('is not sent for a share with no app', async () => {
-        const { handle } = await share(region('global'), 'read');
-        expect(await notificationsFor(handle)).toEqual([]);
-    });
-
-    it('never reaches the desktop wire, and the mint stands when it fails', async () => {
-        const app = await makeApp();
-        const emit = vi.spyOn(state.env.server.clients.event, 'emit');
-        try {
-            const { handle } = await share(region('wire'), 'read', {
-                appUid: app.uid,
-            });
-            const [row] = await notificationsFor(handle);
-            const pushed = emit.mock.calls.filter(
-                ([key, data]) =>
-                    key === 'outer.gui.notif.message' &&
-                    JSON.stringify(data).includes(row.uid),
-            );
-            expect(pushed).toEqual([]);
-        } finally {
-            emit.mockRestore();
-        }
-
-        const notify = vi
-            .spyOn(state.env.server.services.notification, 'notify')
-            .mockRejectedValueOnce(new Error('mailbox down'));
-        try {
-            await expect(
-                share(region('failing'), 'read', { appUid: app.uid }),
-            ).resolves.toMatchObject({ access: 'read' });
-        } finally {
-            notify.mockRestore();
-        }
-    });
-
-    it('stays out of the whole-mailbox listing, but not out of the app`s slice', async () => {
-        const app = await makeApp();
-        const { handle } = await share(region('select'), 'read', {
-            appUid: app.uid,
-        });
-        const [row] = await notificationsFor(handle);
-        const select = (actor: Actor, args: Record<string, unknown> = {}) =>
-            runWithContext({ actor }, () =>
-                state.env.server.drivers.notifications.select(args),
-            ) as Promise<Array<{ uid: unknown }>>;
-        const uids = (rows: Array<{ uid: unknown }>) =>
-            rows.map((one) => one.uid);
-
-        expect(uids(await select(state.guest.actor))).not.toContain(row.uid);
-        expect(
-            uids(
-                await select(state.guest.actor, { subject: 'notif:app-user' }),
-            ),
-        ).not.toContain(row.uid);
-        expect(
-            uids(
-                await select(state.guest.actor, {
-                    subject: `notif:${app.uid}:app-user`,
-                }),
-            ),
-        ).toContain(row.uid);
-        const appActor = makeActor({
-            user: state.guest.actor.user as never,
-            app: { uid: app.uid, id: app.id },
-        });
-        expect(uids(await select(appActor))).toContain(row.uid);
-    });
-
-    it('is left out of the unread replay a desktop gets on connecting', async () => {
-        const app = await makeApp();
-        const { handle } = await share(region('replay'), 'read', {
-            appUid: app.uid,
-        });
-        const [row] = await notificationsFor(handle);
-        const emit = vi.spyOn(state.env.server.clients.event, 'emit');
-        try {
-            state.env.server.clients.event.emit(
-                'web.socket.user-connected',
-                { user: { id: state.guest.id } } as never,
-                {},
-            );
-            // The replay is debounced by two seconds.
-            await new Promise((resolve) => setTimeout(resolve, 2_300));
-            const replayed = emit.mock.calls.filter(
-                ([key, data]) =>
-                    key === 'outer.gui.notif.unreads' &&
-                    JSON.stringify(data).includes(row.uid),
-            );
-            expect(replayed).toEqual([]);
-        } finally {
-            emit.mockRestore();
-        }
-    });
-});
-
-describe('the share notification with notification dispatch on', () => {
-    const { state, makeApp, share, notificationsFor } = bootEnv({
-        events: {
-            enabled: true,
-            kvHandles: true,
-            notificationsFoldIn: true,
-        },
-    });
-
-    it('reaches the app`s notif:app-user subscription and never the desktop', async () => {
-        const app = await makeApp();
-        const delivered: DeliveryEnvelope[] = [];
-        state.env.server.services.events.onDelivered = (envelope) =>
-            delivered.push(envelope);
-        const appActor = makeActor({
-            user: state.guest.actor.user as never,
-            app: { uid: app.uid, id: app.id },
-        });
-        await state.env.server.services.events.subscribe(
-            appActor,
-            'kv-recipient-socket',
-            { subject: 'notif:app-user' },
-        );
-        const send = vi.spyOn(state.env.server.services.socket, 'send');
-        try {
-            const { handle } = await share(region('folded'), 'read', {
-                appUid: app.uid,
-            });
-            const [row] = await notificationsFor(handle);
-
-            await vi.waitFor(
-                () =>
-                    expect(
-                        delivered.some(
-                            (one) =>
-                                (one.event as { uid?: string }).uid === row.uid,
-                        ),
-                    ).toBe(true),
-                { timeout: EVENTS_COALESCE_WINDOW_MS * 12, interval: 25 },
-            );
-            const desktop = send.mock.calls.filter(
-                ([, key, data]) =>
-                    key === 'notif.message' &&
-                    JSON.stringify(data).includes(row.uid),
-            );
-            expect(desktop).toEqual([]);
-        } finally {
-            send.mockRestore();
-            await state.env.server.services.events.reapSocket(
-                state.guest.id,
-                'kv-recipient-socket',
-            );
-        }
-    });
-
-    it('stays out of the desktop`s own notif:app-user feed, live and fetched', async () => {
-        const events = state.env.server.services.events;
-        const app = await makeApp();
-        const delivered: DeliveryEnvelope[] = [];
-        events.onDelivered = (envelope) => delivered.push(envelope);
-        const appActor = makeActor({
-            user: state.guest.actor.user as never,
-            app: { uid: app.uid, id: app.id },
-        });
-        const { sub: desktopSub } = await events.subscribe(
-            state.guest.actor,
-            'kv-recipient-desktop',
-            { subject: 'notif:app-user' },
-        );
-        const { sub: appSub } = await events.subscribe(
-            appActor,
-            'kv-recipient-app',
-            { subject: 'notif:app-user' },
-        );
-        const deliveredTo = (subId: string, uid: string) =>
-            delivered.some(
-                (one) =>
-                    one.subId === subId &&
-                    (one.event as { uid?: string }).uid === uid,
-            );
-        // Deliveries on one subject within the coalesce window collapse to the
-        // last, so each notification is waited out before the next is sent.
-        const waitFor = (check: () => boolean) =>
-            vi.waitFor(() => expect(check()).toBe(true), {
-                timeout: EVENTS_COALESCE_WINDOW_MS * 12,
-                interval: 25,
-            });
-        try {
-            const { handle } = await share(region('desktop'), 'read', {
-                appUid: app.uid,
-            });
-            const [row] = await notificationsFor(handle);
-            await waitFor(() => deliveredTo(appSub.subId, row.uid));
-
-            // Another app-user row about the same app still reaches the desktop.
-            const ended = (await state.env.server.services.notification.notify(
-                [state.guest.id],
-                { title: 'Subscription ended' },
-                { type: 'app.events.ended', appUid: app.uid },
-            ))!;
-            await waitFor(() => deliveredTo(desktopSub.subId, ended));
-            expect(deliveredTo(desktopSub.subId, row.uid)).toBe(false);
-
-            const fetched = async (subject: string) =>
-                (
-                    await events.fetchMissed(state.guest.actor, { subject })
-                ).items.map((item) => item.uid);
-            const generic = await fetched('notif:app-user');
-            expect(generic).toContain(ended);
-            expect(generic).not.toContain(row.uid);
-            expect(await fetched(`notif:${app.uid}:app-user`)).toContain(
-                row.uid,
-            );
-        } finally {
-            for (const socketId of ['kv-recipient-desktop', 'kv-recipient-app'])
-                await events.reapSocket(state.guest.id, socketId);
-        }
-    });
-});
-
-describe('recipient share blocks', () => {
-    const { state, makeApp, share, notificationsFor } = bootEnv({});
-
-    it('refuse a share from a sender the recipient blocked', async () => {
-        await state.env.server.stores.userBlock.create(
-            state.guest.id,
-            state.owner.id,
-        );
-        try {
-            const app = await makeApp();
-            await expect(
-                share(region('blocked'), 'read', { appUid: app.uid }),
-            ).rejects.toMatchObject({
-                statusCode: 403,
-                legacyCode: 'recipient_not_accepting_shares',
-            });
-            const listed =
-                await state.env.server.services.kvShare.listKvHandles(
-                    state.owner.actor,
-                    { limit: 200 },
-                );
-            expect(
-                listed.items.filter((row) => row.appUid === app.uid),
-            ).toEqual([]);
-        } finally {
-            await state.env.server.stores.userBlock.deleteByPair(
-                state.guest.id,
-                state.owner.id,
-            );
-        }
-    });
-
-    it('refuse a share when the recipient refuses everyone', async () => {
-        await state.env.server.stores.user.updateMetadata(state.guest.id, {
-            blockAllShares: true,
-        });
-        try {
-            await expect(share(region('all'), 'watch')).rejects.toMatchObject({
-                legacyCode: 'recipient_not_accepting_shares',
-            });
-        } finally {
-            await state.env.server.stores.user.updateMetadata(state.guest.id, {
-                blockAllShares: false,
-            });
-        }
-    });
-
-    it('leave a share made before the block to be narrowed, its label cleared, and revoked', async () => {
-        const app = await makeApp();
-        const prefix = region('before');
-        const { handle } = await share(prefix, 'write', {
-            appUid: app.uid,
-            label: 'Before',
-        });
-        await state.env.server.stores.userBlock.create(
-            state.guest.id,
-            state.owner.id,
-        );
-        try {
-            await expect(
-                share(prefix, 'read', { appUid: app.uid, label: null }),
-            ).resolves.toMatchObject({
-                handle,
-                access: 'read',
-                label: null,
-            });
-            await expect(
-                state.env.server.services.kvShare.removeKvShare(
-                    state.owner.actor,
-                    handle,
-                ),
-            ).resolves.toMatchObject({ handle });
-            // Still only the notification from before the block.
-            expect(await notificationsFor(handle)).toHaveLength(1);
-        } finally {
-            await state.env.server.stores.userBlock.deleteByPair(
-                state.guest.id,
-                state.owner.id,
-            );
-        }
-    });
-
-    it.each([
-        ['a raised level', { access: 'write' as const }],
-        ['a new label', { label: 'Later' }],
-        [
-            'a lower level with a new label',
-            { access: 'watch' as const, label: 'Later' },
-        ],
-    ])('refuse %s on a share made before the block', async (_name, change) => {
-        const app = await makeApp();
-        const prefix = region('raise');
-        const { handle } = await share(prefix, 'read', { appUid: app.uid });
-        await state.env.server.stores.userBlock.create(
-            state.guest.id,
-            state.owner.id,
-        );
-        try {
-            await expect(
-                share(prefix, 'access' in change ? change.access : 'read', {
-                    appUid: app.uid,
-                    ...('label' in change ? { label: change.label } : {}),
-                }),
-            ).rejects.toMatchObject({
-                legacyCode: 'recipient_not_accepting_shares',
-            });
-            const row =
-                await state.env.server.stores.kvShareHandle.getByHandle(handle);
-            expect(row).toMatchObject({ revokedAt: null, label: null });
-            expect(row?.permission.startsWith('kv-share-read:')).toBe(true);
-        } finally {
-            await state.env.server.stores.userBlock.deleteByPair(
-                state.guest.id,
-                state.owner.id,
-            );
-        }
-    });
-});

src/backend/services/kvShare/kvShares.test.ts

@@ -1,868 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import { describe, expect, it, vi } from 'vitest';
-import type { Actor } from '../../core/actor.js';
-import { HttpError } from '../../core/http/HttpError.js';
-import { PermissionUtil } from '../permission/permissionUtil.js';
-import {
-    assertBoundedManageGrant,
-    assertNewShareSegments,
-    assertPrefixFitsAccess,
-    assertShareableAppUid,
-    assertShareablePrefix,
-    isKvShareManagePermission,
-    isKvSharePermission,
-    keyPrefixSegments,
-    KV_SHARE_PREFIX_MAX_BYTES,
-    kvShareAccessOf,
-    kvShareAppDelegateImplicator,
-    kvShareGrantAtEveryLevel,
-    kvShareGrantCovers,
-    kvShareGrantPrefix,
-    kvShareLevelForMethod,
-    kvShareLevelsExploder,
-    kvShareManageNamespaceRoots,
-    kvShareManagePermission,
-    kvShareOwnerImplicator,
-    kvSharePermission,
-    mintKvHandleId,
-    normalizeKeyPrefix,
-    parseKvShareAccess,
-    parseKvShareLabel,
-    parseKvShareRecipient,
-    relativeToKvShareRoot,
-    withKvShareAccess,
-} from './kvShares.js';
-import { APP_DATA_KV_METHOD_OPS } from '../permission/appDataScopes.js';
-import { isKvHandleId, kvHandleFromSubject } from '../events/subjects.js';
-
-const OWNER = '2a1b0c9d-0000-4000-8000-000000000001';
-const OTHER = '2a1b0c9d-0000-4000-8000-000000000002';
-const APP = 'app-1234';
-const OTHER_APP = 'app-5678';
-
-const userActor = (uuid: string): Actor =>
-    ({ user: { uuid }, effectiveApp: null }) as unknown as Actor;
-
-const appActor = (uuid: string, appUid: string): Actor =>
-    ({
-        user: { uuid },
-        app: { uid: appUid },
-        effectiveApp: { uid: appUid },
-    }) as unknown as Actor;
-
-describe('the share permission family', () => {
-    it('names the owner, the app and the granted prefix', () => {
-        expect(kvSharePermission(OWNER, APP, 'workspace:abc:')).toBe(
-            `kv-share:${OWNER}:${APP}:workspace:abc`,
-        );
-    });
-
-    it('makes key segments components, so a deeper key is a descendant', () => {
-        const granted = kvSharePermission(OWNER, APP, 'workspace:abc:');
-        const deeper = kvSharePermission(
-            OWNER,
-            APP,
-            'workspace:abc:messages:1',
-        );
-
-        // The exploder walks parents of the string being checked, so implication
-        // over key segments needs nothing of its own.
-        expect(deeper.startsWith(`${granted}:`)).toBe(true);
-    });
-
-    it('escapes a `:` inside a component rather than splitting on it', () => {
-        const permission = kvSharePermission(OWNER, 'app:odd', 'cart:');
-        expect(PermissionUtil.split(permission)).toEqual([
-            'kv-share',
-            OWNER,
-            'app:odd',
-            'cart',
-        ]);
-    });
-
-    it('reads a withdrawn grant as covering itself and everything under it', () => {
-        const granted = kvSharePermission(OWNER, APP, 'workspace:abc:');
-        expect(kvShareGrantCovers(granted, granted)).toBe(true);
-        expect(
-            kvShareGrantCovers(
-                granted,
-                kvSharePermission(OWNER, APP, 'workspace:abc:messages:'),
-            ),
-        ).toBe(true);
-        // A sibling that merely shares a text prefix is a different region.
-        expect(
-            kvShareGrantCovers(
-                granted,
-                kvSharePermission(OWNER, APP, 'workspace:abcdef:'),
-            ),
-        ).toBe(false);
-        expect(
-            kvShareGrantCovers(
-                granted,
-                kvSharePermission(OTHER, APP, 'workspace:abc:'),
-            ),
-        ).toBe(false);
-        // Coverage never crosses namespaces: the app uid is what keeps a
-        // revoke inside the one the handle was minted in.
-        expect(
-            kvShareGrantCovers(
-                granted,
-                kvSharePermission(OWNER, OTHER_APP, 'workspace:abc:messages:'),
-            ),
-        ).toBe(false);
-    });
-
-    it('never reads a withdrawn child as covering its own parent', () => {
-        // Revoking the deeper of two grants must not read as covering the
-        // shallower one — coverage only ever runs downward.
-        const child = kvSharePermission(OWNER, APP, 'workspace:abc:messages:');
-        const parent = kvSharePermission(OWNER, APP, 'workspace:abc:');
-        expect(kvShareGrantCovers(child, parent)).toBe(false);
-    });
-});
-
-describe('granted prefixes', () => {
-    it('always ends on the key delimiter', () => {
-        expect(normalizeKeyPrefix('workspace:abc')).toBe('workspace:abc:');
-        expect(normalizeKeyPrefix('workspace:abc:')).toBe('workspace:abc:');
-        expect(keyPrefixSegments('workspace:abc:')).toEqual([
-            'workspace',
-            'abc',
-        ]);
-    });
-
-    it.each([
-        ['', 'the whole namespace'],
-        [':', 'delimiters only'],
-        ['workspace:*', 'a pattern'],
-        ['workspace:a?c', 'a single-character pattern'],
-        // Normalizing would drop the empty segment and grant `a:b:` instead —
-        // a region other than the one asked for.
-        ['workspace::abc:', 'an empty key segment'],
-        [':workspace:abc:', 'a leading empty segment'],
-        // `escape_permission_component` leaves `\\` alone while escaping `:`,
-        // so the stored prefix and the permission string would disagree and
-        // the share would silently never fire.
-        ['work\\space:abc:', 'a backslash'],
-    ])('refuses %s (%s)', (prefix) => {
-        let thrown: unknown;
-        try {
-            assertShareablePrefix(prefix);
-        } catch (err) {
-            thrown = err;
-        }
-        expect(thrown).toBeInstanceOf(HttpError);
-        expect((thrown as HttpError).legacyCode).toBe(
-            'invalid_kv_share_prefix',
-        );
-    });
-
-    it('refuses a region too deep to fit the grant column', () => {
-        expect(() =>
-            assertPrefixFitsAccess(OWNER, APP, 'a'.repeat(300), 'watch'),
-        ).toThrow(HttpError);
-        expect(
-            assertPrefixFitsAccess(OWNER, APP, 'workspace:abc:', 'watch'),
-        ).toBe(kvSharePermission(OWNER, APP, 'workspace:abc:'));
-    });
-
-    it('keeps the trailing delimiter optional', () => {
-        expect(assertShareablePrefix('workspace:abc')).toBe('workspace:abc:');
-        expect(assertShareablePrefix('workspace:abc:')).toBe('workspace:abc:');
-    });
-});
-
-describe('granted namespaces', () => {
-    it('takes an app uid, and the app-less namespace', () => {
-        expect(assertShareableAppUid(APP)).toBe(APP);
-        expect(assertShareableAppUid('os-global')).toBe('os-global');
-    });
-
-    it('refuses one past the column it is stored in', () => {
-        // A longer one reaches the insert as a write the column cannot hold.
-        let thrown: unknown;
-        try {
-            assertShareableAppUid('a'.repeat(41));
-        } catch (err) {
-            thrown = err;
-        }
-        expect(thrown).toBeInstanceOf(HttpError);
-        expect((thrown as HttpError).statusCode).toBe(400);
-    });
-
-    it('takes both shapes a real app uid comes in', () => {
-        // Minted (`app-<uuidv4>`) and derived from an origin (`app-<uuidv5>`)
-        // — 40 characters either way, which is the column exactly.
-        const minted = `app-${uuidv4()}`;
-        expect(assertShareableAppUid(minted)).toBe(minted);
-        expect(minted).toHaveLength(40);
-    });
-
-    it('refuses a handle, which shares the slot but is not a namespace', () => {
-        expect(() => assertShareableAppUid(mintKvHandleId())).toThrow(
-            HttpError,
-        );
-    });
-
-    it('refuses anything else short enough to fit the column', () => {
-        // The slot ends up in a subject and in a permission string, so a
-        // namespace carrying a delimiter of either grammar is refused before
-        // it can be composed into one.
-        for (const uid of [
-            'os-globals',
-            'workspace:abc',
-            'app',
-            'app-',
-            'app-a:b',
-            'app-a#b',
-            'v1:someone:app-x',
-            '',
-        ])
-            expect(() => assertShareableAppUid(uid)).toThrow(HttpError);
-    });
-});
-
-describe('keys inside a granted region', () => {
-    const permission = kvSharePermission(OWNER, APP, 'workspace:abc:');
-
-    it('are named relative to the granted root', () => {
-        expect(
-            relativeToKvShareRoot(permission, 'workspace:abc:messages:1'),
-        ).toBe('messages:1');
-    });
-
-    it('read as outside when they are', () => {
-        expect(
-            relativeToKvShareRoot(permission, 'workspace:abcdef:x'),
-        ).toBeNull();
-        expect(relativeToKvShareRoot(permission, 'workspace:abc')).toBeNull();
-    });
-});
-
-describe('a delegation request', () => {
-    const region = kvShareManagePermission(
-        kvSharePermission(OWNER, APP, 'workspace:abc:'),
-    );
-
-    it('is the manage arm of the grant it would let an app issue', () => {
-        expect(region).toBe(`manage:kv-share:${OWNER}:${APP}:workspace:abc`);
-        expect(assertBoundedManageGrant(region)).toBe(region);
-    });
-
-    it.each([
-        ['manage:kv-share', 'the family itself'],
-        [`manage:kv-share:${OWNER}`, 'an owner and no namespace'],
-        [`manage:kv-share:${OWNER}:${APP}`, 'a whole namespace'],
-    ])('refuses %s (%s)', (permission) => {
-        let thrown: unknown;
-        try {
-            assertBoundedManageGrant(permission);
-        } catch (err) {
-            thrown = err;
-        }
-        expect(thrown).toBeInstanceOf(HttpError);
-        expect((thrown as HttpError).legacyCode).toBe(
-            'invalid_kv_share_prefix',
-        );
-    });
-
-    it('leaves permissions from other families alone', () => {
-        const unrelated = `manage:fs:${OWNER}:write`;
-        expect(assertBoundedManageGrant(unrelated)).toBe(unrelated);
-        // The read arm of this family is not a delegation, so it is not this
-        // check's to bound.
-        expect(assertBoundedManageGrant(`kv-share:${OWNER}:${APP}`)).toBeTypeOf(
-            'string',
-        );
-    });
-});
-
-describe('handle ids', () => {
-    it('are told apart from an app uid in the same slot', () => {
-        const handle = mintKvHandleId();
-        expect(isKvHandleId(handle)).toBe(true);
-        expect(isKvHandleId(APP)).toBe(false);
-        expect(isKvHandleId('kvh-')).toBe(false);
-    });
-
-    it('carry nothing about the owner', () => {
-        const handle = mintKvHandleId();
-        expect(handle).not.toContain(OWNER);
-        expect(mintKvHandleId()).not.toBe(handle);
-    });
-
-    it('are recoverable from the subject a row stored', () => {
-        const handle = mintKvHandleId();
-        expect(kvHandleFromSubject(`kv:${handle}:messages:*`)).toBe(handle);
-        expect(kvHandleFromSubject(`kv:${APP}:messages:*`)).toBeNull();
-        expect(kvHandleFromSubject(`fs:${handle}:write`)).toBeNull();
-    });
-});
-
-describe('the owner implicator', () => {
-    const implicator = kvShareOwnerImplicator();
-    const permission = kvSharePermission(OWNER, APP, 'workspace:abc:');
-
-    it('answers the share family and its manage arm', () => {
-        expect(implicator.matches(permission)).toBe(true);
-        expect(implicator.matches(`manage:${permission}`)).toBe(true);
-        expect(implicator.matches(`fs:${OWNER}:read`)).toBe(false);
-    });
-
-    it('holds for the owner named in the permission, and nobody else', () => {
-        expect(
-            implicator.check({ actor: userActor(OWNER), permission }),
-        ).toEqual({});
-        expect(
-            implicator.check({
-                actor: userActor(OWNER),
-                permission: `manage:${permission}`,
-            }),
-        ).toEqual({});
-        expect(
-            implicator.check({ actor: userActor(OTHER), permission }),
-        ).toBeUndefined();
-    });
-
-    it('reads the owner past a `manage` key segment', () => {
-        // Stripping every `manage:` rather than the leading one would rewrite
-        // the string the owner is read out of.
-        const nested = kvSharePermission(OWNER, APP, 'manage:secrets:');
-        expect(implicator.matches(nested)).toBe(true);
-        expect(
-            implicator.check({ actor: userActor(OWNER), permission: nested }),
-        ).toEqual({});
-        expect(
-            implicator.check({ actor: userActor(OTHER), permission: nested }),
-        ).toBeUndefined();
-    });
-
-    it('never answers for an app or a token acting through the owner', () => {
-        const appActor = {
-            user: { uuid: OWNER },
-            app: { uid: APP },
-        } as unknown as Actor;
-        expect(
-            implicator.check({ actor: appActor, permission }),
-        ).toBeUndefined();
-    });
-});
-
-describe('the app delegate implicator', () => {
-    const permission = kvSharePermission(OWNER, APP, 'workspace:abc:');
-
-    it('answers the share family, never its manage arm, nor other families', () => {
-        const implicator = kvShareAppDelegateImplicator({
-            userHolds: vi.fn(),
-        });
-        expect(implicator.matches(permission)).toBe(true);
-        expect(implicator.matches(`manage:${permission}`)).toBe(false);
-        expect(implicator.matches(`fs:${OWNER}:read`)).toBe(false);
-    });
-
-    it("grants when the actor's own app matches the namespace app and the user holds the grant", async () => {
-        const userHolds = vi.fn().mockResolvedValue(true);
-        const implicator = kvShareAppDelegateImplicator({ userHolds });
-        const actor = appActor(OWNER, APP);
-
-        await expect(implicator.check({ actor, permission })).resolves.toEqual(
-            {},
-        );
-
-        expect(userHolds).toHaveBeenCalledTimes(1);
-        const [calledActor, calledPermission] = userHolds.mock.calls[0];
-        expect(calledActor.app).toBeUndefined();
-        expect(calledActor.effectiveApp).toBeNull();
-        expect(calledActor.user).toEqual({ uuid: OWNER });
-        expect(calledPermission).toBe(permission);
-    });
-
-    it('refuses when the user does not hold the grant', async () => {
-        const implicator = kvShareAppDelegateImplicator({
-            userHolds: vi.fn().mockResolvedValue(false),
-        });
-        await expect(
-            implicator.check({ actor: appActor(OWNER, APP), permission }),
-        ).resolves.toBeUndefined();
-    });
-
-    it("refuses when the actor's app differs from the namespace app", async () => {
-        const userHolds = vi.fn().mockResolvedValue(true);
-        const implicator = kvShareAppDelegateImplicator({ userHolds });
-
-        await expect(
-            implicator.check({
-                actor: appActor(OWNER, OTHER_APP),
-                permission,
-            }),
-        ).resolves.toBeUndefined();
-        expect(userHolds).not.toHaveBeenCalled();
-    });
-
-    it('refuses a plain user actor with no app', async () => {
-        const userHolds = vi.fn().mockResolvedValue(true);
-        const implicator = kvShareAppDelegateImplicator({ userHolds });
-
-        await expect(
-            implicator.check({ actor: userActor(OWNER), permission }),
-        ).resolves.toBeUndefined();
-        expect(userHolds).not.toHaveBeenCalled();
-    });
-
-    it('refuses an access-token actor', async () => {
-        const userHolds = vi.fn().mockResolvedValue(true);
-        const implicator = kvShareAppDelegateImplicator({ userHolds });
-        const actor = {
-            user: { uuid: OWNER },
-            app: { uid: APP },
-            accessToken: { uid: 't' },
-        } as unknown as Actor;
-
-        await expect(
-            implicator.check({ actor, permission }),
-        ).resolves.toBeUndefined();
-        expect(userHolds).not.toHaveBeenCalled();
-    });
-
-    it('asks the user once for a deep option and the ancestors its check already asked', async () => {
-        const userHolds = vi.fn().mockResolvedValue(false);
-        const implicator = kvShareAppDelegateImplicator({ userHolds });
-        const actor = appActor(OWNER, APP);
-        const memo = new Map<string, unknown>();
-        const deep = kvSharePermission(OWNER, APP, 'a:b:c:', 'read');
-        for (const permission of [
-            deep,
-            kvSharePermission(OWNER, APP, 'a:b:c:', 'write'),
-            kvSharePermission(OWNER, APP, 'a:b:', 'read'),
-            kvSharePermission(OWNER, APP, 'a:', 'write'),
-        ])
-            await expect(
-                implicator.check({ actor, permission, memo }),
-            ).resolves.toBeUndefined();
-        expect(userHolds).toHaveBeenCalledTimes(1);
-
-        // A lower level, or a region beside it, is a question of its own.
-        await implicator.check({
-            actor,
-            permission: kvSharePermission(OWNER, APP, 'a:b:', 'watch'),
-            memo,
-        });
-        await implicator.check({
-            actor,
-            permission: kvSharePermission(OWNER, APP, 'a:x:', 'read'),
-            memo,
-        });
-        expect(userHolds).toHaveBeenCalledTimes(3);
-
-        // Nothing carries over to another scan.
-        await implicator.check({ actor, permission: deep });
-        expect(userHolds).toHaveBeenCalledTimes(4);
-    });
-
-    it('refuses a permission with no key segments or no app', async () => {
-        const userHolds = vi.fn().mockResolvedValue(true);
-        const implicator = kvShareAppDelegateImplicator({ userHolds });
-        const actor = appActor(OWNER, APP);
-
-        await expect(
-            implicator.check({
-                actor,
-                permission: PermissionUtil.join('kv-share', OWNER, APP),
-            }),
-        ).resolves.toBeUndefined();
-        await expect(
-            implicator.check({
-                actor,
-                permission: PermissionUtil.join('kv-share', OWNER),
-            }),
-        ).resolves.toBeUndefined();
-        expect(userHolds).not.toHaveBeenCalled();
-    });
-});
-
-/** The refusal a call threw, for asserting on its code. */
-const refusal = (fn: () => unknown): HttpError => {
-    try {
-        fn();
-    } catch (err) {
-        if (err instanceof HttpError) return err;
-        throw err;
-    }
-    throw new Error('expected a refusal');
-};
-
-describe('share levels', () => {
-    const REGION = 'workspace:abc:';
-
-    it('put the level in the root, leaving watch grants as they were', () => {
-        expect(kvSharePermission(OWNER, APP, REGION)).toBe(
-            `kv-share:${OWNER}:${APP}:workspace:abc`,
-        );
-        expect(kvSharePermission(OWNER, APP, REGION, 'read')).toBe(
-            `kv-share-read:${OWNER}:${APP}:workspace:abc`,
-        );
-        expect(kvSharePermission(OWNER, APP, REGION, 'write')).toBe(
-            `kv-share-write:${OWNER}:${APP}:workspace:abc`,
-        );
-    });
-
-    it('read the level back off any root, and nothing else as the family', () => {
-        for (const access of ['watch', 'read', 'write'] as const) {
-            const permission = kvSharePermission(OWNER, APP, REGION, access);
-            expect(isKvSharePermission(permission)).toBe(true);
-            expect(kvShareAccessOf(permission)).toBe(access);
-            expect(kvShareGrantPrefix(permission)).toBe(REGION);
-            expect(
-                relativeToKvShareRoot(permission, `${REGION}messages:1`),
-            ).toBe('messages:1');
-        }
-        expect(isKvSharePermission(`kv-shared:${OWNER}`)).toBe(false);
-        expect(isKvSharePermission(`kv-share-admin:${OWNER}`)).toBe(false);
-        expect(kvShareAccessOf(`fs:${OWNER}:read`)).toBeNull();
-    });
-
-    it('swap only the root when moving a grant between levels', () => {
-        const read = kvSharePermission(OWNER, APP, REGION, 'read');
-        expect(withKvShareAccess(read, 'write')).toBe(
-            kvSharePermission(OWNER, APP, REGION, 'write'),
-        );
-        expect(kvShareGrantAtEveryLevel(read)).toEqual([
-            kvSharePermission(OWNER, APP, REGION, 'watch'),
-            read,
-            kvSharePermission(OWNER, APP, REGION, 'write'),
-        ]);
-    });
-
-    it('cover a region withdrawn at one level at every level', () => {
-        const writeRegion = kvSharePermission(OWNER, APP, REGION, 'write');
-        const watchInside = kvSharePermission(OWNER, APP, `${REGION}messages:`);
-        expect(kvShareGrantCovers(writeRegion, watchInside)).toBe(true);
-        expect(
-            kvShareGrantCovers(
-                kvSharePermission(OWNER, APP, REGION, 'read'),
-                kvSharePermission(OWNER, APP, REGION, 'write'),
-            ),
-        ).toBe(true);
-        // Still never upward, and never across namespaces.
-        expect(kvShareGrantCovers(watchInside, writeRegion)).toBe(false);
-        expect(
-            kvShareGrantCovers(
-                writeRegion,
-                kvSharePermission(OWNER, OTHER_APP, REGION, 'write'),
-            ),
-        ).toBe(false);
-        // Nothing outside the family is ever covered.
-        expect(kvShareGrantCovers(writeRegion, `fs:${OWNER}:read`)).toBe(false);
-    });
-});
-
-describe('the level ladder exploder', () => {
-    const exploder = kvShareLevelsExploder();
-    const at = (access: 'watch' | 'read' | 'write') =>
-        kvSharePermission(OWNER, APP, 'workspace:abc:', access);
-
-    it('lets a check at a level be answered by every level above it', async () => {
-        expect(await exploder.explode({ permission: at('watch') })).toEqual([
-            at('watch'),
-            at('read'),
-            at('write'),
-        ]);
-        expect(await exploder.explode({ permission: at('read') })).toEqual([
-            at('read'),
-            at('write'),
-        ]);
-        expect(exploder.matches(at('write'))).toBe(false);
-    });
-
-    it('ladders a manage arm the same way', async () => {
-        expect(
-            await exploder.explode({ permission: `manage:${at('read')}` }),
-        ).toEqual([`manage:${at('read')}`, `manage:${at('write')}`]);
-    });
-
-    it('never ladders a string with no key segment', async () => {
-        for (const permission of [
-            PermissionUtil.join('kv-share', OWNER, APP),
-            PermissionUtil.join('manage', 'kv-share-read', OWNER, APP),
-            PermissionUtil.join('kv-share', OWNER),
-            'kv-share',
-        ])
-            expect(await exploder.explode({ permission })).toEqual([
-                permission,
-            ]);
-    });
-
-    it('leaves other families alone', () => {
-        expect(exploder.matches(`fs:${OWNER}:read`)).toBe(false);
-        expect(exploder.matches(`app-data:${APP}:kv:read`)).toBe(false);
-    });
-});
-
-describe('the level a driver method needs', () => {
-    it('is read for get and list, and write for every other mapped op', () => {
-        expect(kvShareLevelForMethod('get')).toBe('read');
-        expect(kvShareLevelForMethod('list')).toBe('read');
-        for (const method of [
-            'set',
-            'batchPut',
-            'add',
-            'incr',
-            'decr',
-            'update',
-            'del',
-            'remove',
-            'expire',
-            'expireAt',
-        ])
-            expect(kvShareLevelForMethod(method)).toBe('write');
-    });
-
-    it('refuses flush and anything the op table does not name', () => {
-        expect(kvShareLevelForMethod('flush')).toBeNull();
-        expect(kvShareLevelForMethod('toString')).toBeNull();
-        expect(kvShareLevelForMethod('somethingNew')).toBeNull();
-    });
-
-    it('covers every method the op table knows', () => {
-        for (const [method, op] of Object.entries(APP_DATA_KV_METHOD_OPS))
-            expect(kvShareLevelForMethod(method) === null).toBe(op === null);
-    });
-});
-
-describe('share request parsing', () => {
-    it('takes the three levels and a fallback, and refuses anything else', () => {
-        expect(parseKvShareAccess(undefined, 'read')).toBe('read');
-        expect(parseKvShareAccess(null, 'watch')).toBe('watch');
-        expect(parseKvShareAccess('write', 'read')).toBe('write');
-        for (const value of ['delete', 'WRITE', '', 2, {}])
-            expect(
-                refusal(() => parseKvShareAccess(value, 'read')).legacyCode,
-            ).toBe('kv_share_access_invalid');
-    });
-
-    it('caps a prefix at what the grant column leaves for its owner, app and level', () => {
-        const owner = uuidv4();
-        const app = `app-${uuidv4()}`;
-        // 255 less the root, the owner uuid, the app uid and two separators.
-        const longest = { watch: 169, read: 164, write: 163 } as const;
-        for (const access of ['watch', 'read', 'write'] as const) {
-            const fits = `${'a'.repeat(longest[access] - 1)}:`;
-            const over = `${'a'.repeat(longest[access])}:`;
-            expect(
-                assertPrefixFitsAccess(owner, app, fits, access),
-            ).toHaveLength(255);
-            const refused = refusal(() =>
-                assertPrefixFitsAccess(owner, app, over, access),
-            );
-            expect(refused.legacyCode).toBe('invalid_kv_share_prefix');
-            expect(refused.message).toContain(`${longest[access]} characters`);
-        }
-        // The app-less namespace has a shorter name, so more room.
-        expect(() =>
-            assertPrefixFitsAccess(
-                owner,
-                'os-global',
-                `${'a'.repeat(193)}:`,
-                'write',
-            ),
-        ).not.toThrow();
-    });
-
-    it('holds a multibyte read or write prefix to the byte cap', () => {
-        const multibyte = `${'é'.repeat(KV_SHARE_PREFIX_MAX_BYTES / 2)}:`;
-        expect(
-            refusal(() => assertPrefixFitsAccess(OWNER, APP, multibyte, 'read'))
-                .legacyCode,
-        ).toBe('invalid_kv_share_prefix');
-        expect(() =>
-            assertPrefixFitsAccess(OWNER, APP, multibyte, 'watch'),
-        ).not.toThrow();
-    });
-
-    it('takes a recipient as a username or an object, never an address', () => {
-        expect(parseKvShareRecipient(' alice ')).toEqual({
-            username: 'alice',
-        });
-        expect(parseKvShareRecipient({ username: 'alice' })).toEqual({
-            username: 'alice',
-        });
-        expect(parseKvShareRecipient({ uid: OWNER })).toEqual({ uid: OWNER });
-        for (const value of [
-            '[email protected]',
-            { username: 'a@b' },
-            '',
-            {},
-            [],
-            42,
-            null,
-            undefined,
-        ])
-            expect(refusal(() => parseKvShareRecipient(value)).legacyCode).toBe(
-                'invalid_recipient',
-            );
-    });
-
-    it('trims a label, reads empty as none, and keeps absent apart from null', () => {
-        expect(parseKvShareLabel(undefined)).toBeUndefined();
-        expect(parseKvShareLabel(null)).toBeNull();
-        expect(parseKvShareLabel('   ')).toBeNull();
-        expect(parseKvShareLabel('  Japan 2027 · from dan ')).toBe(
-            'Japan 2027 · from dan',
-        );
-    });
-
-    it.each([
-        ['a control character', 'trip\u0007'],
-        ['a newline', 'trip\nplans'],
-        ['a line separator', 'trip\u2028plans'],
-        ['a paragraph separator', 'trip\u2029plans'],
-        ['a bidi override', 'trip\u202Eplans'],
-        ['a bidi isolate', 'trip\u2067plans'],
-        ['a left-to-right mark', 'trip\u200Eplans'],
-        ['a right-to-left mark', 'trip\u200Fplans'],
-        ['an Arabic letter mark', 'trip\u061Cplans'],
-        ['a zero-width space', 'trip\u200Bplans'],
-        ['a zero-width joiner', 'trip\u200Dplans'],
-        ['a zero-width non-joiner', 'trip\u200Cplans'],
-        ['a word joiner', 'trip\u2060plans'],
-        ['a soft hyphen', 'trip\u00ADplans'],
-        ['a byte order mark', 'trip\uFEFFplans'],
-        ['a tag character', 'trip\u{E0041}plans'],
-        ['an interlinear annotation anchor', 'trip\uFFF9plans'],
-        ['four combining marks on one character', 'e\u0301\u0302\u0303\u0304'],
-        ['a non-string', 42],
-        ['too many characters', 'x'.repeat(129)],
-        ['too many bytes', '😀'.repeat(129)],
-    ])('refuses a label with %s', (_case, value) => {
-        expect(refusal(() => parseKvShareLabel(value)).legacyCode).toBe(
-            'kv_share_label_invalid',
-        );
-    });
-
-    it('holds a new share`s key segments to lowercase letters, digits, `_`, `.` and `-`', () => {
-        expect(() =>
-            assertNewShareSegments(['room_1.a-b', 'x9']),
-        ).not.toThrow();
-        for (const segment of ['Room', 'café', 'a b', 'a*', 'ß', 'İ'])
-            expect(
-                refusal(() => assertNewShareSegments(['ok', segment]))
-                    .legacyCode,
-            ).toBe('invalid_kv_share_prefix');
-    });
-
-    it('takes a label at the character cap', () => {
-        expect(parseKvShareLabel('x'.repeat(128))).toBe('x'.repeat(128));
-    });
-
-    it('takes up to three combining marks on a character, and emoji with a variation selector', () => {
-        expect(parseKvShareLabel('e\u0301\u0302\u0303 caf\u00E9')).toBe(
-            'e\u0301\u0302\u0303 caf\u00E9',
-        );
-        expect(parseKvShareLabel('Trip \u2764\uFE0F')).toBe(
-            'Trip \u2764\uFE0F',
-        );
-    });
-});
-
-describe('delegations at every level', () => {
-    it('are bounded the same way at every level', () => {
-        for (const access of ['watch', 'read', 'write'] as const) {
-            const region = kvShareManagePermission(
-                kvSharePermission(OWNER, APP, 'workspace:abc:', access),
-            );
-            expect(isKvShareManagePermission(region)).toBe(true);
-            expect(assertBoundedManageGrant(region)).toBe(region);
-            const root = PermissionUtil.join(
-                'manage',
-                access === 'watch' ? 'kv-share' : `kv-share-${access}`,
-                OWNER,
-                APP,
-            );
-            expect(
-                refusal(() => assertBoundedManageGrant(root)).legacyCode,
-            ).toBe('invalid_kv_share_prefix');
-        }
-    });
-
-    it('name the namespace root at every level for the unbounded check', () => {
-        expect(
-            kvShareManageNamespaceRoots(
-                kvSharePermission(OWNER, APP, 'workspace:abc:', 'read'),
-            ),
-        ).toEqual([
-            `manage:kv-share:${OWNER}:${APP}`,
-            `manage:kv-share-read:${OWNER}:${APP}`,
-            `manage:kv-share-write:${OWNER}:${APP}`,
-        ]);
-    });
-
-    it('are answered for the owner at every level, and never by the app delegate', () => {
-        const owner = kvShareOwnerImplicator();
-        const delegate = kvShareAppDelegateImplicator({ userHolds: vi.fn() });
-        for (const access of ['read', 'write'] as const) {
-            const permission = kvSharePermission(
-                OWNER,
-                APP,
-                'workspace:abc:',
-                access,
-            );
-            expect(owner.matches(permission)).toBe(true);
-            expect(owner.matches(`manage:${permission}`)).toBe(true);
-            expect(
-                owner.check({ actor: userActor(OWNER), permission }),
-            ).toEqual({});
-            expect(
-                owner.check({ actor: userActor(OTHER), permission }),
-            ).toBeUndefined();
-            expect(delegate.matches(permission)).toBe(true);
-            expect(delegate.matches(`manage:${permission}`)).toBe(false);
-        }
-    });
-
-    it('let a holder`s app use a read or write grant only in its own namespace', async () => {
-        const userHolds = vi.fn().mockResolvedValue(true);
-        const delegate = kvShareAppDelegateImplicator({ userHolds });
-        const permission = kvSharePermission(
-            OWNER,
-            APP,
-            'workspace:abc:',
-            'write',
-        );
-        await expect(
-            delegate.check({ actor: appActor(OTHER, APP), permission }),
-        ).resolves.toEqual({});
-        await expect(
-            delegate.check({ actor: appActor(OTHER, OTHER_APP), permission }),
-        ).resolves.toBeUndefined();
-        await expect(
-            delegate.check({
-                actor: appActor(OTHER, OTHER_APP),
-                permission: kvSharePermission(
-                    OWNER,
-                    'os-global',
-                    'workspace:abc:',
-                    'read',
-                ),
-            }),
-        ).resolves.toBeUndefined();
-    });
-});

src/backend/services/kvShare/kvShares.ts

@@ -1,628 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import { randomUUID } from 'node:crypto';
-import {
-    type Actor,
-    isAppActor,
-    isPlainUserActor,
-    userRelatedActor,
-} from '../../core/actor.js';
-import { HttpError } from '../../core/http/HttpError.js';
-import { KV_SHARE_HANDLE_WIDTHS } from '../../stores/events/columnWidths.js';
-import {
-    KV_GLOBAL_APP_KEY,
-    KV_MAX_KEY_BYTES,
-} from '../../stores/systemKv/SystemKVStore.js';
-import {
-    MANAGE_PERM_PREFIX,
-    PERMISSION_MAX_LEN,
-} from '../permission/consts.js';
-import { APP_DATA_KV_METHOD_OPS } from '../permission/appDataScopes.js';
-import type {
-    PermissionExploder,
-    PermissionImplicator,
-} from '../permission/permissionUtil.js';
-import { PermissionUtil } from '../permission/permissionUtil.js';
-import {
-    isKvHandleId,
-    KV_HANDLE_PREFIX,
-    KV_KEY_SEPARATOR,
-} from '../events/subjects.js';
-
-/**
- * Letting one user watch, read or write a region of another's key-value
- * namespace.
- *
- * The grant is an ordinary user-to-user permission, which is the whole point:
- * `manage:` answers "may I delegate this", the exploder's prefix implication
- * makes a grant on `workspace:abc:` answer every key beneath it, and revocation
- * settling and the delivery re-check key off the stored string exactly as they
- * do for a shared folder. Putting the ACL on the key-value item instead would
- * take part in none of that, and would tax every write to the item besides.
- *
- * The permission names the owner, so its components are the three things a
- * shared region is, under a root that names the access level:
- *
- *     kv-share:<ownerUserUuid>:<appUid>:<keySegment>...         watch
- *     kv-share-read:<ownerUserUuid>:<appUid>:<keySegment>...    read
- *     kv-share-write:<ownerUserUuid>:<appUid>:<keySegment>...   write
- *
- * The level is in the root rather than a component so the permission system
- * enforces it, and so the strings `kv-share:` grants already use keep their
- * meaning.
- *
- * Key segments are components rather than one escaped blob because that is what
- * makes prefix implication work without a rule of its own: the check a deep key
- * runs is a descendant of the grant string, and the existing parent walk finds
- * it. The grantee never sees this string — the handle is the name on the wire.
- */
-
-/** Root of the cross-user key-value share namespace, at the watch level. */
-export const KV_SHARE_PERMISSION_PREFIX = 'kv-share';
-
-/** Access levels, lowest first. Each implies the ones before it. */
-export const KV_SHARE_ACCESS_LEVELS = ['watch', 'read', 'write'] as const;
-export type KvShareAccess = (typeof KV_SHARE_ACCESS_LEVELS)[number];
-
-const KV_SHARE_ROOTS: Record<KvShareAccess, string> = {
-    watch: KV_SHARE_PERMISSION_PREFIX,
-    read: `${KV_SHARE_PERMISSION_PREFIX}-read`,
-    write: `${KV_SHARE_PERMISSION_PREFIX}-write`,
-};
-
-/** The permission root a level is granted under. */
-export const kvShareRoot = (access: KvShareAccess): string =>
-    KV_SHARE_ROOTS[access];
-
-const ACCESS_BY_ROOT = new Map<string, KvShareAccess>(
-    KV_SHARE_ACCESS_LEVELS.map((access) => [KV_SHARE_ROOTS[access], access]),
-);
-
-/**
- * Byte ceiling on a `read` or `write` prefix, which the fixed relative-key
- * limit assumes. The grant column binds first for every prefix a new share may
- * name; this one only bites on a multibyte prefix shared before that rule.
- */
-export const KV_SHARE_PREFIX_MAX_BYTES = 256;
-
-/**
- * Longest key a call through a handle may name, relative to the handle, in
- * UTF-8 bytes: what the store's key limit leaves after the longest prefix, so
- * the limit a holder hits says nothing about how long the prefix is.
- */
-export const KV_HANDLE_KEY_MAX_BYTES =
-    KV_MAX_KEY_BYTES - KV_SHARE_PREFIX_MAX_BYTES;
-
-/** Width of the `app_uid` column the handle row stores its namespace in. */
-export const KV_SHARE_APP_UID_MAX_LENGTH = KV_SHARE_HANDLE_WIDTHS.appUid.max;
-
-export const mintKvHandleId = (): string =>
-    `${KV_HANDLE_PREFIX}${randomUUID()}`;
-
-/** The key segments a prefix contributes to a permission string. */
-export const keyPrefixSegments = (keyPrefix: string): string[] =>
-    keyPrefix.split(KV_KEY_SEPARATOR).filter((segment) => segment.length > 0);
-
-/**
- * A granted prefix as it is stored: always ending on the key delimiter, so
- * `keyPrefix + relative` is a whole key and the region never accidentally
- * includes the key that names it.
- */
-export const normalizeKeyPrefix = (keyPrefix: string): string => {
-    const segments = keyPrefixSegments(keyPrefix);
-    return segments.length === 0
-        ? ''
-        : `${segments.join(KV_KEY_SEPARATOR)}${KV_KEY_SEPARATOR}`;
-};
-
-export const kvSharePermission = (
-    ownerUserUuid: string,
-    appUid: string,
-    keyPrefix: string,
-    access: KvShareAccess = 'watch',
-): string =>
-    PermissionUtil.join(
-        KV_SHARE_ROOTS[access],
-        ownerUserUuid,
-        appUid,
-        ...keyPrefixSegments(keyPrefix),
-    );
-
-/** The family root a permission starts with, or `null` outside the family. */
-const kvShareRootOf = (permission: string): string | null => {
-    const end = permission.indexOf(':');
-    const head = end === -1 ? permission : permission.slice(0, end);
-    return ACCESS_BY_ROOT.has(head) ? head : null;
-};
-
-export const isKvSharePermission = (permission: string): boolean =>
-    kvShareRootOf(permission) !== null;
-
-/** The access level a share grant carries, or `null` outside the family. */
-export const kvShareAccessOf = (permission: string): KvShareAccess | null => {
-    const root = kvShareRootOf(permission);
-    return root === null ? null : (ACCESS_BY_ROOT.get(root) ?? null);
-};
-
-/** The same grant at another level: only the root changes. */
-export const withKvShareAccess = (
-    permission: string,
-    access: KvShareAccess,
-): string => {
-    const root = kvShareRootOf(permission);
-    if (root === null) return permission;
-    return `${KV_SHARE_ROOTS[access]}${permission.slice(root.length)}`;
-};
-
-/** The grant at every level, for withdrawing a region whatever it was. */
-export const kvShareGrantAtEveryLevel = (permission: string): string[] =>
-    KV_SHARE_ACCESS_LEVELS.map((access) =>
-        withKvShareAccess(permission, access),
-    );
-
-/**
- * Whether withdrawing `revoked` takes `held` with it. Prefix implication read
- * backwards: a grant answers every check at or beneath it, so withdrawing it
- * puts every one of those in question. Compared below the root, because a
- * region withdrawn at one level is in question at every level.
- */
-export const kvShareGrantCovers = (revoked: string, held: string): boolean => {
-    const revokedRoot = kvShareRootOf(revoked);
-    const heldRoot = kvShareRootOf(held);
-    if (revokedRoot === null || heldRoot === null) return false;
-    const region = revoked.slice(revokedRoot.length);
-    const inside = held.slice(heldRoot.length);
-    return inside === region || inside.startsWith(`${region}:`);
-};
-
-/**
- * The level a key-value driver method needs through a share, or `null` for a
- * method no share reaches. Derived from the cross-app op table, so a method
- * missing from it fails closed.
- */
-export const kvShareLevelForMethod = (method: string): KvShareAccess | null => {
-    if (!Object.prototype.hasOwnProperty.call(APP_DATA_KV_METHOD_OPS, method))
-        return null;
-    const op = APP_DATA_KV_METHOD_OPS[method];
-    if (op === null) return null;
-    return op === 'get' || op === 'list' ? 'read' : 'write';
-};
-
-/** The granted root a share grant names, read back as a key prefix. */
-export const kvShareGrantPrefix = (permission: string): string =>
-    normalizeKeyPrefix(
-        PermissionUtil.split(permission).slice(3).join(KV_KEY_SEPARATOR),
-    );
-
-/**
- * A key inside a granted region, named the way its holder addresses it, or
- * `null` for one outside. The handle is the granted root, so everything the
- * holder is shown is relative to it — an absolute key would name a namespace
- * they cannot address and were never told about.
- */
-export const relativeToKvShareRoot = (
-    permission: string,
-    key: string,
-): string | null => {
-    const prefix = kvShareGrantPrefix(permission);
-    if (!prefix || !key.startsWith(prefix)) return null;
-    return key.slice(prefix.length);
-};
-
-/**
- * `kv.shareHandles` is off: no `read` or `write` shares, and no calls through
- * one.
- */
-export const kvHandlesDisabled = (): HttpError =>
-    new HttpError(
-        403,
-        'Sharing key-value data for reading or writing is not available',
-        { legacyCode: 'kv_handles_disabled' },
-    );
-
-// -- Minting input ----------------------------------------------------
-
-export const invalidPrefix = (message: string): HttpError =>
-    new HttpError(400, message, { legacyCode: 'invalid_kv_share_prefix' });
-
-const invalidAccess = (message: string): HttpError =>
-    new HttpError(400, message, { legacyCode: 'kv_share_access_invalid' });
-
-/** The level a mint asks for, `fallback` when it names none. */
-export const parseKvShareAccess = (
-    value: unknown,
-    fallback: KvShareAccess,
-): KvShareAccess => {
-    if (value === undefined || value === null) return fallback;
-    if (
-        typeof value !== 'string' ||
-        !(KV_SHARE_ACCESS_LEVELS as readonly string[]).includes(value)
-    )
-        throw invalidAccess('`access` must be `watch`, `read` or `write`');
-    return value as KvShareAccess;
-};
-
-/**
- * The grant a share of `keyPrefix` at `access` would issue, refused with
- * `invalid_kv_share_prefix` when it would not fit the permission column. The
- * room left depends on the owner uuid, the app uid and the level's root, so the
- * longest prefix differs per namespace and level.
- */
-export const assertPrefixFitsAccess = (
-    ownerUuid: string,
-    appUid: string,
-    keyPrefix: string,
-    access: KvShareAccess,
-): string => {
-    const permission = kvSharePermission(ownerUuid, appUid, keyPrefix, access);
-    const prefix = normalizeKeyPrefix(keyPrefix);
-    const room = PERMISSION_MAX_LEN - (permission.length - prefix.length);
-    const overBytes =
-        access !== 'watch' &&
-        Buffer.byteLength(prefix, 'utf8') > KV_SHARE_PREFIX_MAX_BYTES;
-    if (permission.length > PERMISSION_MAX_LEN || overBytes)
-        throw invalidPrefix(
-            `With \`${access}\` access, a share prefix in this namespace may be at most ${room} characters` +
-                (access === 'watch'
-                    ? ''
-                    : ` and ${KV_SHARE_PREFIX_MAX_BYTES} bytes`),
-        );
-    return permission;
-};
-
-const invalidRecipient = (message: string): HttpError =>
-    new HttpError(400, message, { legacyCode: 'invalid_recipient' });
-
-/** Who a share is for, as a username or a user uuid. */
-export interface KvShareRecipient {
-    username?: string;
-    uid?: string;
-}
-
-/**
- * A recipient as `POST /kv/shares` takes it: a username, `{ username }` or `{
- * uid }`. An address is refused rather than looked up, so email recipients can
- * later mean what they mean for file shares.
- */
-export const parseKvShareRecipient = (value: unknown): KvShareRecipient => {
-    const named = (username: unknown): KvShareRecipient => {
-        if (typeof username !== 'string' || username.trim() === '')
-            throw invalidRecipient('`recipient` must name a user');
-        if (username.includes('@'))
-            throw invalidRecipient(
-                '`recipient` must be a username, not an email address',
-            );
-        return { username: username.trim() };
-    };
-    if (typeof value === 'string') return named(value);
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-        const { username, uid } = value as Record<string, unknown>;
-        if (username !== undefined) return named(username);
-        if (typeof uid === 'string' && uid.trim() !== '')
-            return { uid: uid.trim() };
-    }
-    throw invalidRecipient(
-        '`recipient` must be a username, `{ username }` or `{ uid }`',
-    );
-};
-
-const invalidLabel = (message: string): HttpError =>
-    new HttpError(400, message, { legacyCode: 'kv_share_label_invalid' });
-
-export const KV_SHARE_LABEL_MAX_CHARS = 128;
-export const KV_SHARE_LABEL_MAX_BYTES = 512;
-
-/**
- * Control and format characters (bidi marks, overrides and isolates, zero-width
- * characters, BOM, tags) and line or paragraph separators.
- */
-const LABEL_FORBIDDEN = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
-
-/** Combining marks a label may stack on one character. */
-export const KV_SHARE_LABEL_MAX_COMBINING_MARKS = 3;
-const LABEL_MARK_RUN = new RegExp(
-    `\\p{M}{${KV_SHARE_LABEL_MAX_COMBINING_MARKS + 1},}`,
-    'u',
-);
-
-/**
- * An owner-set label. `undefined` leaves the stored one alone, `null` clears
- * it, and a string that trims to nothing reads as `null`.
- */
-export const parseKvShareLabel = (
-    value: unknown,
-): string | null | undefined => {
-    if (value === undefined) return undefined;
-    if (value === null) return null;
-    if (typeof value !== 'string')
-        throw invalidLabel('`label` must be a string');
-    const label = value.trim();
-    if (label === '') return null;
-    if (LABEL_FORBIDDEN.test(label))
-        throw invalidLabel(
-            '`label` may not contain control, formatting, line-break or text-direction characters',
-        );
-    if (LABEL_MARK_RUN.test(label))
-        throw invalidLabel(
-            `\`label\` may not stack more than ${KV_SHARE_LABEL_MAX_COMBINING_MARKS} combining marks on one character`,
-        );
-    if (
-        [...label].length > KV_SHARE_LABEL_MAX_CHARS ||
-        Buffer.byteLength(label, 'utf8') > KV_SHARE_LABEL_MAX_BYTES
-    )
-        throw invalidLabel(
-            `\`label\` may not exceed ${KV_SHARE_LABEL_MAX_CHARS} characters or ${KV_SHARE_LABEL_MAX_BYTES} bytes`,
-        );
-    return label;
-};
-
-export const invalidAppUid = (message: string): HttpError =>
-    new HttpError(400, message, { legacyCode: 'bad_request' });
-
-/**
- * The region a handle may be minted on. A pattern is refused because a handle
- * names a region rather than selecting within one, and the namespace root is
- * refused because a handle over everything the app holds is not a bounded
- * capability — it is the app's data, and sharing that is a different decision
- * with a different consent.
- */
-export const assertShareablePrefix = (keyPrefix: unknown): string => {
-    if (typeof keyPrefix !== 'string')
-        throw invalidPrefix('`prefix` must be a string');
-    if (keyPrefix.includes('*') || keyPrefix.includes('?'))
-        throw invalidPrefix('A share prefix is a key prefix, not a pattern');
-    // `escape_permission_component` escapes `:` as `\C` but leaves `\` alone,
-    // so a prefix carrying one desynchronizes the stored `key_prefix` from the
-    // permission string and the share silently never fires.
-    if (keyPrefix.includes('\\'))
-        throw invalidPrefix('A share prefix may not contain a backslash');
-    // Normalizing drops empty segments, so `a::b:` would silently become a
-    // grant on `a:b:` — a region other than the one asked for. Refused rather
-    // than rewritten; only the trailing delimiter is optional.
-    const written = keyPrefix.split(KV_KEY_SEPARATOR);
-    if (written[written.length - 1] === '') written.pop();
-    if (written.some((segment) => segment === ''))
-        throw invalidPrefix('A share prefix may not have an empty key segment');
-
-    const normalized = normalizeKeyPrefix(keyPrefix);
-    if (normalized === '')
-        throw invalidPrefix('A share prefix may not be the whole namespace');
-    return normalized;
-};
-
-const NEW_SHARE_SEGMENT = /^[a-z0-9_.-]+$/;
-
-/**
- * The key segments a new share or share consent may name. One spelling per
- * region, so no two grants differ only in case or accents, which some databases
- * compare as equal. Existing shares are not held to it.
- */
-export const assertNewShareSegments = (segments: readonly string[]): void => {
-    if (segments.some((segment) => !NEW_SHARE_SEGMENT.test(segment)))
-        throw invalidPrefix(
-            'A share prefix may only contain lowercase letters (a-z), digits, `_`, `.` and `-` between its `:` separators',
-        );
-};
-
-/** A new share over a prefix that an existing share spells differently. */
-export const kvSharePrefixCaseConflict = (): HttpError =>
-    invalidPrefix(
-        'This user already has a share of a prefix that differs from this one only in letter case',
-    );
-
-/**
- * The shape every app uid takes, minted or derived from an origin. Narrow on
- * purpose: `:` and `#` delimit the anchor token and permission grammars, so
- * excluding them matters as much as excluding the handle prefix does.
- */
-export const APP_UID_SHAPE = /^app-[A-Za-z0-9_-]{1,64}$/;
-
-/** Fixed namespaces with no app of their own. */
-const FIXED_KV_NAMESPACES: readonly string[] = [KV_GLOBAL_APP_KEY];
-
-/**
- * The namespace a handle may be minted over: the caller's own app slot, or the
- * app-less one. Bounded by the column that stores it, shaped like a real app
- * uid or one of the platform's fixed namespaces, and never handle-shaped, since
- * the two share the app slot of a `kv:` subject.
- */
-export const assertShareableAppUid = (appUid: string): string => {
-    if (appUid.length > KV_SHARE_APP_UID_MAX_LENGTH)
-        throw invalidAppUid(
-            `\`appUid\` may not exceed ${KV_SHARE_APP_UID_MAX_LENGTH} characters`,
-        );
-    if (isKvHandleId(appUid))
-        throw invalidAppUid('A share handle does not name a namespace');
-    if (!APP_UID_SHAPE.test(appUid) && !FIXED_KV_NAMESPACES.includes(appUid))
-        throw invalidAppUid('`appUid` does not name a namespace');
-    return appUid;
-};
-
-// -- Delegation -------------------------------------------------------
-
-/** The delegation arm of a share grant: authority to hand the region out. */
-export const kvShareManagePermission = (permission: string): string =>
-    PermissionUtil.join(
-        MANAGE_PERM_PREFIX,
-        ...PermissionUtil.split(permission),
-    );
-
-export const isKvShareManagePermission = (permission: string): boolean =>
-    PermissionUtil.isManage(permission) &&
-    isKvSharePermission(permission.slice(MANAGE_PERM_PREFIX.length + 1));
-
-/**
- * A delegation must name a subtree. Consent on the namespace root reads as "let
- * this app hand out anything it has stored for you", which is not a bounded
- * capability and so is not something a prompt can put to a user.
- */
-export const assertBoundedManageGrant = (permission: string): string => {
-    if (!isKvShareManagePermission(permission)) return permission;
-    const [, , owner, appUid, ...segments] = PermissionUtil.split(permission);
-    if (!owner || !appUid || segments.length === 0)
-        throw invalidPrefix(
-            'A share delegation must name a region, not the whole namespace',
-        );
-    return permission;
-};
-
-/**
- * The unbounded `manage:` grants, one per level, that a bounded delegation's
- * own permission sits in. The consent surface refuses to ever write these rows,
- * but `canManagePermission` walks ancestors to decide "may I delegate this", so
- * one that exists by any other path would silently authorize a mint anywhere in
- * the namespace. This is what lets the mint path notice it regardless.
- */
-export const kvShareManageNamespaceRoots = (permission: string): string[] => {
-    const [, owner, appUid] = PermissionUtil.split(permission);
-    return KV_SHARE_ACCESS_LEVELS.map((access) =>
-        PermissionUtil.join(
-            MANAGE_PERM_PREFIX,
-            KV_SHARE_ROOTS[access],
-            owner,
-            appUid,
-        ),
-    );
-};
-
-// -- Permission rules -------------------------------------------------
-
-/**
- * The level ladder: a check at one level is also answered by a grant at any
- * level above it, `manage:` arms included. Only a string with at least one key
- * segment is laddered, so no level of a namespace-root grant answers another.
- */
-export const kvShareLevelsExploder = (): PermissionExploder => ({
-    id: 'kv-share-levels',
-    matches: (permission: string): boolean => {
-        const access = kvShareAccessOf(
-            PermissionUtil.stripManageArms(permission),
-        );
-        return access !== null && access !== 'write';
-    },
-    explode: ({ permission }): string[] => {
-        const grant = PermissionUtil.stripManageArms(permission);
-        const arms = permission.slice(0, permission.length - grant.length);
-        const access = kvShareAccessOf(grant);
-        // Owner, app, and at least one key segment after the root.
-        if (access === null || grant.split(':').length < 4) return [permission];
-        const above = KV_SHARE_ACCESS_LEVELS.slice(
-            KV_SHARE_ACCESS_LEVELS.indexOf(access) + 1,
-        );
-        return [
-            permission,
-            ...above.map(
-                (level) => `${arms}${withKvShareAccess(grant, level)}`,
-            ),
-        ];
-    },
-});
-
-/**
- * The permission a `manage:` arm delegates over. Only the leading component is
- * stripped: a key segment may itself be `manage`, and taking those out would
- * change which string the owner is read from.
- */
-const withoutManageArm = (permission: string): string =>
-    permission.startsWith(`${MANAGE_PERM_PREFIX}:`)
-        ? permission.slice(MANAGE_PERM_PREFIX.length + 1)
-        : permission;
-
-/**
- * Owning the namespace is holding every share grant over it, and being able to
- * issue them. Without this the owner cannot mint a handle on their own data:
- * `grantUserUserPermission` asks `canManagePermission` first, and there is no
- * row anywhere saying a user may manage what is already theirs.
- *
- * Restricted to plain user actors, as the filesystem's `is-owner` is. An app
- * disposing of a region of its user's namespace is delegation, which is the
- * `manage:` grant's job rather than this one's.
- */
-export const kvShareOwnerImplicator = (): PermissionImplicator => ({
-    id: 'kv-share-is-owner',
-    shortcut: true,
-    matches: (permission: string): boolean =>
-        isKvSharePermission(withoutManageArm(permission)),
-    check: ({ actor, permission }): unknown => {
-        if (!isPlainUserActor(actor)) return undefined;
-        const uuid = actor.user?.uuid;
-        if (!uuid) return undefined;
-
-        const owner = PermissionUtil.split(withoutManageArm(permission))[1];
-        return owner === uuid ? {} : undefined;
-    },
-});
-
-/** Scan memo key for the grants a user check already refused. */
-const DELEGATE_REFUSED = 'kv-share-app-delegate:refused';
-
-/**
- * Whether a check of `asked` also asks `option`: `option` is `asked` or an
- * ancestor of it, at the same level or above.
- */
-const kvShareCheckReaches = (asked: string, option: string): boolean => {
-    const askedAccess = kvShareAccessOf(asked);
-    const optionAccess = kvShareAccessOf(option);
-    if (askedAccess === null || optionAccess === null) return false;
-    return (
-        KV_SHARE_ACCESS_LEVELS.indexOf(optionAccess) >=
-            KV_SHARE_ACCESS_LEVELS.indexOf(askedAccess) &&
-        kvShareGrantCovers(option, asked)
-    );
-};
-
-/**
- * Letting an app-under-user actor exercise a share grant its user holds, at any
- * level, bounded to the app the grant's namespace names.
- *
- * Only the grant itself is matched — never `manage:kv-share…` — because
- * answering the manage arm here would read as the unbounded namespace-root
- * delegation and break minting for everyone (see
- * `kvShareManageNamespaceRoots`). The namespace-app check keeps one app from
- * reading a region shared with another app of the same user.
- */
-export const kvShareAppDelegateImplicator = (deps: {
-    userHolds: (actor: Actor, permission: string) => Promise<boolean>;
-}): PermissionImplicator => ({
-    id: 'kv-share-app-delegate',
-    shortcut: true,
-    matches: (permission: string): boolean => isKvSharePermission(permission),
-    check: async ({ actor, permission, memo }): Promise<unknown> => {
-        if (!isAppActor(actor)) return undefined;
-        const app = actor.effectiveApp;
-        if (!app?.uid) return undefined;
-
-        const [, owner, namespaceApp, ...segments] =
-            PermissionUtil.split(permission);
-        if (!owner || !namespaceApp || segments.length === 0) return undefined;
-        if (namespaceApp !== app.uid) return undefined;
-
-        // A scan offers the deepest option first, and the user check of one
-        // also asks its ancestors at its level or above, so its refusal
-        // answers those without asking again.
-        const refused = memo?.get(DELEGATE_REFUSED) as string[] | undefined;
-        if (refused?.some((asked) => kvShareCheckReaches(asked, permission)))
-            return undefined;
-        if (await deps.userHolds(userRelatedActor(actor), permission))
-            return {};
-        memo?.set(DELEGATE_REFUSED, [...(refused ?? []), permission]);
-        return undefined;
-    },
-});

src/backend/services/metering/enforcement.ts

@@ -223,23 +223,6 @@ export const actorOnPaidPlan = async (
     return subscriptionSatisfies(subscription.id, true);
 };
 
-/**
- * The actor's plan id, for tiered limits. `null` with no metering to ask, or
- * when the lookup fails, which the tier tables read as their default.
- */
-export const actorPlanId = async (
-    metering: SubscriptionMetering | undefined,
-    actor: Actor,
-): Promise<string | null> => {
-    if (!metering) return null;
-    try {
-        return (await metering.getActorSubscription(actor)).id;
-    } catch (err) {
-        console.warn('[metering] could not resolve a plan', err);
-        return null;
-    }
-};
-
 /**
  * Where a plan gate sits, so a `subscription.gate.<surface>` listener can waive
  * it for a call it recognizes. `surface` is the key segment after

src/backend/services/notification/NotificationService.ts

@@ -28,8 +28,6 @@ import {
 } from './notificationSocket.js';
 import {
     findNotificationType,
-    inAccountMailbox,
-    OUTSIDE_ACCOUNT_MAILBOX_TYPES,
     resolveNotificationWrite,
 } from './notificationTypes.js';
 import type { NotificationTypeName } from './notificationTypes.js';
@@ -245,7 +243,6 @@ export class NotificationService extends PuterService {
      * message the GUI has always listened for.
      */
     deliverOverSocket(context: NotifEventContext): void {
-        if (!inAccountMailbox(context.type)) return;
         this.#socket().message(
             context.userId,
             context.uid,
@@ -302,9 +299,7 @@ export class NotificationService extends PuterService {
         payload: Record<string, unknown>,
         scope: { type: string; audience: string; appUid: string | null },
     ): Promise<void> {
-        const desktop = inAccountMailbox(scope.type);
         if (!notificationsFoldInEnabled(this.config)) {
-            if (!desktop) return;
             this.#socket().message(userId, uid, payload);
             this.#markDelivered(uid, userId);
             return;
@@ -314,7 +309,6 @@ export class NotificationService extends PuterService {
         // looked up only on this path, and user rows are cached.
         const user = await this.stores.user.getById(userId);
         if (!user?.uuid) {
-            if (!desktop) return;
             this.#socket().message(userId, uid, payload);
             this.#markDelivered(uid, userId);
             return;
@@ -338,7 +332,7 @@ export class NotificationService extends PuterService {
             },
             {},
         );
-        if (desktop) this.#markDelivered(uid, userId);
+        this.#markDelivered(uid, userId);
     }
 
     /**
@@ -378,7 +372,6 @@ export class NotificationService extends PuterService {
         const rows = await this.stores.notification.listByUserId(userId, {
             filter: 'unseen',
             limit: UNREAD_REPLAY_LIMIT,
-            excludeTypes: OUTSIDE_ACCOUNT_MAILBOX_TYPES,
         });
         if (rows.length === 0) return;
 

src/backend/services/notification/notificationTypes.test.ts

@@ -20,9 +20,7 @@
 import { describe, expect, it } from 'vitest';
 import {
     NOTIFICATION_TYPES,
-    OUTSIDE_ACCOUNT_MAILBOX_TYPES,
     findNotificationType,
-    inAccountMailbox,
     resolveNotificationWrite,
 } from './notificationTypes.js';
 
@@ -130,28 +128,3 @@ describe('resolveNotificationWrite', () => {
         );
     });
 });
-
-describe('types kept off the account mailbox', () => {
-    it('are only the ones an app alone has a use for', () => {
-        expect(OUTSIDE_ACCOUNT_MAILBOX_TYPES).toEqual(['kv.share.received']);
-        for (const entry of NOTIFICATION_TYPES)
-            expect(inAccountMailbox(entry.type)).toBe(
-                entry.type !== 'kv.share.received',
-            );
-        // An unclassified legacy row still belongs on the desktop.
-        expect(inAccountMailbox('')).toBe(true);
-        expect(inAccountMailbox(undefined)).toBe(true);
-    });
-
-    it('include the key-value share notice, which always names its app', () => {
-        expect(findNotificationType('kv.share.received')).toMatchObject({
-            audience: 'app-user',
-            appScoped: true,
-            groupable: false,
-            accountMailbox: false,
-        });
-        expect(() =>
-            resolveNotificationWrite('kv.share.received', null),
-        ).toThrow(/requires an app uid/);
-    });
-});

src/backend/services/notification/notificationTypes.ts

@@ -38,12 +38,6 @@ export interface NotificationType {
     appScoped: boolean;
     /** Whether `notifyUpdate` may fold a later one into an open row. */
     groupable: boolean;
-    /**
-     * `false` keeps the type off the account's own desktop: out of the
-     * whole-mailbox listing, the unread replay and the desktop wire. Apps still
-     * read it through its subject. Absent means it shows there.
-     */
-    accountMailbox?: false;
     /** Where a delivery of this type publishes. */
     subject: (ref: NotificationSubjectRef) => string;
 }
@@ -115,16 +109,6 @@ export const NOTIFICATION_TYPES = [
         groupable: false,
         subject: subjectFor('developer'),
     },
-    // A key-value share is news inside the app whose data it is, and nowhere
-    // else: the desktop has nothing to open it with.
-    {
-        type: 'kv.share.received',
-        audience: 'app-user',
-        appScoped: true,
-        groupable: false,
-        accountMailbox: false,
-        subject: subjectFor('app-user'),
-    },
 ] as const satisfies readonly NotificationType[];
 
 /** Every registered type name; what `notify` accepts. */
@@ -141,16 +125,6 @@ export const findNotificationType = (
     type: string,
 ): NotificationType | undefined => BY_NAME.get(type);
 
-/** Types kept off the account's own desktop; see `accountMailbox`. */
-export const OUTSIDE_ACCOUNT_MAILBOX_TYPES: readonly string[] =
-    NOTIFICATION_TYPES.filter(
-        (entry: NotificationType) => entry.accountMailbox === false,
-    ).map((entry) => entry.type);
-
-/** Whether rows of this type belong on the account's own desktop. */
-export const inAccountMailbox = (type: unknown): boolean =>
-    typeof type !== 'string' || !OUTSIDE_ACCOUNT_MAILBOX_TYPES.includes(type);
-
 /**
  * The registry entry for a write, or a throw. `account` rows never name an app;
  * app-scoped rows always do.

src/backend/services/permission/PermissionService.test.ts

@@ -1267,93 +1267,6 @@ describe('PermissionService (integration)', () => {
             expect(flat.filter((v) => !v.deleted)).toHaveLength(0);
         });
 
-        it('revokeUserUserPermissions removes several grants with one delete and one generation bump, announcing each', async () => {
-            const { user: issuer, actor: issuerActor } = await makeUserActor();
-            const { user: target } = await makeUserActor();
-            const tag = uuidv4();
-            const granted = [
-                `zztest:rvk-many-${tag}:a:read`,
-                `zztest:rvk-many-${tag}:b:read`,
-            ];
-            const absent = `zztest:rvk-many-${tag}:c:read`;
-            for (const permission of [...granted, absent])
-                await grantManage(issuer, permission);
-            for (const permission of granted)
-                await runWithContext({ actor: issuerActor }, () =>
-                    permService.grantUserUserPermission(
-                        issuerActor,
-                        target.username,
-                        permission,
-                    ),
-                );
-
-            const store = server.stores.permission;
-            const single = vi.spyOn(store, 'deleteUserUserPermByHolder');
-            const bump = vi.spyOn(store, 'bumpCacheGeneration');
-            const emit = vi.spyOn(server.clients.event, 'emit');
-            let removed: string[];
-            try {
-                removed = await runWithContext({ actor: issuerActor }, () =>
-                    permService.revokeUserUserPermissions(
-                        issuerActor,
-                        target.username,
-                        [...granted, absent],
-                    ),
-                );
-                expect(single).not.toHaveBeenCalled();
-                expect(bump).toHaveBeenCalledTimes(1);
-                expect(
-                    emit.mock.calls
-                        .filter(([key]) => key === 'permission.revoked')
-                        .map(
-                            ([, data]) =>
-                                (data as { permission: string }).permission,
-                        )
-                        .sort(),
-                ).toEqual([...granted].sort());
-            } finally {
-                single.mockRestore();
-                bump.mockRestore();
-                emit.mockRestore();
-            }
-            expect(removed.sort()).toEqual([...granted].sort());
-            expect(
-                await store.readLinkedUserUserPerms(target.id, granted),
-            ).toHaveLength(0);
-            const flat = await store.getFlatUserPerms(target.id, granted);
-            expect(flat.filter((v) => !v.deleted)).toHaveLength(0);
-        });
-
-        it('revokeUserUserPermissions refuses an issuer who may not manage one of them, removing nothing', async () => {
-            const { user: issuer, actor: issuerActor } = await makeUserActor();
-            const { user: target } = await makeUserActor();
-            const managed = `zztest:rvk-auth-${uuidv4()}:ii:read`;
-            const unmanaged = `zztest:rvk-auth-${uuidv4()}:ii:read`;
-            await grantManage(issuer, managed);
-            await runWithContext({ actor: issuerActor }, () =>
-                permService.grantUserUserPermission(
-                    issuerActor,
-                    target.username,
-                    managed,
-                ),
-            );
-            await expect(
-                runWithContext({ actor: issuerActor }, () =>
-                    permService.revokeUserUserPermissions(
-                        issuerActor,
-                        target.username,
-                        [managed, unmanaged],
-                    ),
-                ),
-            ).rejects.toMatchObject({ statusCode: 403 });
-            expect(
-                await server.stores.permission.readLinkedUserUserPerms(
-                    target.id,
-                    [managed],
-                ),
-            ).toHaveLength(1);
-        });
-
         it('grantUserUserPermission persists the linked SQL row before resolving', async () => {
             const { user: issuer, actor: issuerActor } = await makeUserActor();
             const { user: target } = await makeUserActor();

src/backend/services/permission/PermissionService.ts

@@ -510,17 +510,12 @@ export class PermissionService extends PuterService {
         }
 
         // -- shortcut implicators --
-        const memo = new Map<string, unknown>();
         let shortCircuit = false;
         for (const permission of options) {
             for (const implicator of this.implicators) {
                 if (!implicator.shortcut) continue;
                 if (!implicator.matches(permission)) continue;
-                const implied = await implicator.check({
-                    actor,
-                    permission,
-                    memo,
-                });
+                const implied = await implicator.check({ actor, permission });
                 if (!implied) continue;
                 reading.push({
                     $: 'option',
@@ -547,7 +542,7 @@ export class PermissionService extends PuterService {
             // immediately. Scanners only push into `reading`; they don't
             // read each other's writes, so there are no ordering hazards.
             await Promise.all([
-                this.#scanNonShortcutImplicators(actor, options, reading, memo),
+                this.#scanNonShortcutImplicators(actor, options, reading),
                 this.#scanAccessToken(actor, options, reading),
                 this.#scanUserUser(actor, options, reading, workingState),
                 this.#scanUserGroup(actor, options, reading, workingState),
@@ -583,17 +578,12 @@ export class PermissionService extends PuterService {
         actor: Actor,
         options: string[],
         reading: ReadingNode[],
-        memo: Map<string, unknown>,
     ): Promise<void> {
         for (const permission of options) {
             for (const implicator of this.implicators) {
                 if (implicator.shortcut) continue;
                 if (!implicator.matches(permission)) continue;
-                const implied = await implicator.check({
-                    actor,
-                    permission,
-                    memo,
-                });
+                const implied = await implicator.check({ actor, permission });
                 if (!implied) continue;
                 reading.push({
                     $: 'option',
@@ -1277,7 +1267,6 @@ export class PermissionService extends PuterService {
         permission = await this.rewritePermissionForActor(actor, permission);
         const user = await this.#requireUser(username);
         const issuerId = this.#requireUserId(actor);
-        const grantIssuerId = opts.issuerUserId ?? issuerId;
 
         // Giving up access you hold needs no authority over the permission —
         // it can only ever narrow what you can reach.
@@ -1295,7 +1284,7 @@ export class PermissionService extends PuterService {
         const revoked = await this.stores.permission.deleteUserUserPermByHolder(
             user.id,
             permission,
-            grantIssuerId,
+            opts.issuerUserId ?? issuerId,
         );
 
         // The flat key isn't issuer-scoped, so it may only go once no issuer
@@ -1322,11 +1311,11 @@ export class PermissionService extends PuterService {
             this.#audit(
                 this.stores.permission.auditUserUserPerm({
                     holder_user_id: user.id,
-                    issuer_user_id: grantIssuerId,
+                    issuer_user_id: issuerId,
                     permission,
                     action: 'revoke',
                     reason: meta.reason ?? 'revoked via PermissionService',
-                    extra: this.#revokeAuditExtra(actor, grantIssuerId),
+                    extra: this.#auditActorContext(actor),
                 }),
                 'user-user revoke',
             );
@@ -1341,86 +1330,6 @@ export class PermissionService extends PuterService {
         return revoked;
     }
 
-    /**
-     * {@link revokeUserUserPermission} for several permissions of one holder:
-     * one delete, one flat-view cleanup and one generation bump. Returns the
-     * permissions that were removed, each announced on its own.
-     */
-    async revokeUserUserPermissions(
-        actor: Actor,
-        username: string,
-        permissions: readonly string[],
-        meta: GrantMeta = {},
-        opts: { issuerUserId?: number } = {},
-    ): Promise<string[]> {
-        const rewritten = [
-            ...new Set(
-                await Promise.all(
-                    permissions.map((permission) =>
-                        this.rewritePermissionForActor(actor, permission),
-                    ),
-                ),
-            ),
-        ];
-        if (rewritten.length === 0) return [];
-        const user = await this.#requireUser(username);
-        const issuerId = this.#requireUserId(actor);
-        const grantIssuerId = opts.issuerUserId ?? issuerId;
-
-        if (user.id !== issuerId) {
-            await Promise.all(
-                rewritten.map((permission) =>
-                    this.#assertCanManage(actor, permission),
-                ),
-            );
-        }
-
-        const removed =
-            await this.stores.permission.deleteUserUserPermsByHolder(
-                user.id,
-                rewritten,
-                grantIssuerId,
-            );
-
-        // As the single revoke: the flat key goes only where no issuer's grant
-        // remains, read from the primary the delete just landed on. A database
-        // that matches case-insensitively may have removed a row spelled other
-        // than asked, and its flat key is under that spelling.
-        const spellings = [...new Set([...rewritten, ...removed])];
-        const remaining = new Set(
-            (
-                await this.stores.permission.readLinkedUserUserPermsFromPrimary(
-                    user.id,
-                    spellings,
-                )
-            ).map((row) => row.permission),
-        );
-        await this.stores.permission.delFlatUserPerms(
-            spellings
-                .filter((permission) => !remaining.has(permission))
-                .map((permission) => ({ holderUserId: user.id, permission })),
-        );
-
-        for (const permission of removed) {
-            this.#audit(
-                this.stores.permission.auditUserUserPerm({
-                    holder_user_id: user.id,
-                    issuer_user_id: grantIssuerId,
-                    permission,
-                    action: 'revoke',
-                    reason: meta.reason ?? 'revoked via PermissionService',
-                    extra: this.#revokeAuditExtra(actor, grantIssuerId),
-                }),
-                'user-user revoke',
-            );
-        }
-
-        if (user.uuid) await this.#bumpUserCacheGeneration(user.uuid);
-        for (const permission of removed)
-            this.#announceRevoked(user.id, null, permission);
-        return removed;
-    }
-
     /**
      * What an audit row records about who was acting: which app asked, which is
      * the whole question for anything minted under a standing consent.
@@ -1441,45 +1350,6 @@ export class PermissionService extends PuterService {
         return acting?.uid ? { appUid: acting.uid } : null;
     }
 
-    /**
-     * A revoke row is filed under the grant's issuer, so a holder giving up
-     * access never has it in their own trail; who acted goes in `extra`.
-     */
-    #revokeAuditExtra(
-        actor: Actor,
-        grantIssuerId: number,
-    ): Record<string, unknown> | null {
-        const context = this.#auditActorContext(actor);
-        const actingUserId = actor.user?.id;
-        if (actingUserId === undefined || actingUserId === grantIssuerId)
-            return context;
-        return { ...context, actingUserId };
-    }
-
-    /**
-     * Whether this holder has any of `permissions` from this issuer, as a SQL
-     * row or a flat entry: a point lookup, for skipping a revoke with nothing
-     * to remove.
-     */
-    async hasUserUserGrant(
-        holderUserId: number,
-        issuerUserId: number,
-        permissions: readonly string[],
-    ): Promise<boolean> {
-        if (permissions.length === 0) return false;
-        const [rows, flat] = await Promise.all([
-            this.stores.permission.findUserUserPermsByIssuer(
-                holderUserId,
-                issuerUserId,
-                permissions,
-            ),
-            this.stores.permission.getFlatUserPerms(holderUserId, [
-                ...permissions,
-            ]),
-        ]);
-        return rows.length > 0 || flat.some((value) => !value.deleted);
-    }
-
     /**
      * Withdraw a grant and everything the holder was given beneath it.
      *
@@ -1491,34 +1361,27 @@ export class PermissionService extends PuterService {
      * business.
      *
      * Returns the permissions removed. Each is announced separately, because
-     * each is a distinct thing something may have been standing on. Several
-     * roots go in one delete and one generation bump.
+     * each is a distinct thing something may have been standing on.
      */
     async revokeUserUserPermissionSubtree(
         actor: Actor,
         username: string,
-        permission: string | readonly string[],
+        permission: string,
         meta: GrantMeta = {},
     ): Promise<string[]> {
-        const roots = await Promise.all(
-            (typeof permission === 'string' ? [permission] : permission).map(
-                (root) => this.rewritePermissionForActor(actor, root),
-            ),
-        );
+        permission = await this.rewritePermissionForActor(actor, permission);
         const user = await this.#requireUser(username);
         const issuerId = this.#requireUserId(actor);
 
         if (user.id !== issuerId) {
-            await Promise.all(
-                roots.map((root) => this.#assertCanManage(actor, root)),
-            );
+            await this.#assertCanManage(actor, permission);
         }
 
         const removed =
             await this.stores.permission.deleteUserUserPermSubtreeForHolder(
                 user.id,
                 issuerId,
-                roots,
+                permission,
             );
 
         for (const removedPermission of removed) {

src/backend/services/permission/appGrantable.test.ts

@@ -1,179 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import { describe, expect, it } from 'vitest';
-import { parseAppGrantablePermission } from './appGrantable.js';
-
-const ME = '2f5d8a8e-6b8f-4a43-9a0b-3d6f3f0f9b11';
-const OTHER = '9c1e4b7a-1f2d-4c3b-8a5e-6d7f8091a2b3';
-const APP = 'app-5d4f2c1e-8b3a-4f6d-9e7c-1a2b3c4d5e6f';
-const FILE = 'b3c1d2e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e';
-
-const parse = (permission: string) =>
-    parseAppGrantablePermission(permission, ME);
-
-describe('parseAppGrantablePermission', () => {
-    it.each([
-        [
-            `fs:/alice/Documents:read`,
-            { family: 'fs', target: '/alice/Documents', mode: 'read' },
-        ],
-        [`fs:${FILE}:write`, { family: 'fs', target: FILE, mode: 'write' }],
-        [
-            `fs:/alice/a\\Cb.txt:see`,
-            { family: 'fs', target: '/alice/a:b.txt', mode: 'see' },
-        ],
-        [
-            `fs:/alice/a\\\\b.txt:read`,
-            { family: 'fs', target: '/alice/a\\b.txt', mode: 'read' },
-        ],
-        [`fs:/alice:list`, { family: 'fs', target: '/alice', mode: 'list' }],
-        [`user:${ME}:email:read`, { family: 'email' }],
-        [`apps-of-user:${ME}:read`, { family: 'apps', access: 'read' }],
-        [
-            `subdomains-of-user:${ME}:write`,
-            { family: 'subdomains', access: 'write' },
-        ],
-        [`app-data:${APP}`, { family: 'appData', appUid: APP }],
-        [`app-data:${APP}:kv`, { family: 'appData', appUid: APP, store: 'kv' }],
-        [
-            `app-data:${APP}:kv:expireAt`,
-            { family: 'appData', appUid: APP, store: 'kv', scope: 'expireAt' },
-        ],
-        [
-            `app-data:${APP}:fs:delete`,
-            { family: 'appData', appUid: APP, store: 'fs', scope: 'delete' },
-        ],
-        [
-            `app-root-dir:${APP}:write`,
-            { family: 'appRootDir', appUid: APP, access: 'write' },
-        ],
-        [
-            `manage:kv-share:${ME}:${APP}:rooms:abc`,
-            {
-                family: 'kvShare',
-                level: 'watch',
-                ownerUuid: ME,
-                appUid: APP,
-                segments: ['rooms', 'abc'],
-            },
-        ],
-        [
-            `manage:kv-share-read:${ME}:${APP}:rooms:abc`,
-            {
-                family: 'kvShare',
-                level: 'read',
-                ownerUuid: ME,
-                appUid: APP,
-                segments: ['rooms', 'abc'],
-            },
-        ],
-        [
-            `manage:kv-share-write:${ME}:${APP}:rooms`,
-            {
-                family: 'kvShare',
-                level: 'write',
-                ownerUuid: ME,
-                appUid: APP,
-                segments: ['rooms'],
-            },
-        ],
-        ['events:background', { family: 'backgroundEvents' }],
-    ])('accepts %s', (permission, parsed) => {
-        expect(parse(permission)).toEqual(parsed);
-    });
-
-    it.each([
-        // Never checked for an app, so a grant would only confuse the prompt.
-        'service:ai-chat:ii:puter-chat-completion',
-        'driver:puter-image-generation:generate',
-        'thread:abc:post',
-        'site:example',
-        'feature',
-        // Internal or wider than any prompt can describe.
-        `manage:fs:${FILE}:write`,
-        `manage:fs:/alice/Documents`,
-        `kv-share:${ME}:${APP}:rooms`,
-        `kv-share-read:${ME}:${APP}:rooms`,
-        `kv-share-write:${ME}:${APP}:rooms`,
-        `app:uid#${APP}:access`,
-        'flag:app-is-authenticated',
-        'full-api-access',
-        '*',
-        'events',
-        'events:background:extra',
-        // Modeless, or a mode that does not exist.
-        'fs',
-        `fs:${FILE}`,
-        `fs:${FILE}:delete`,
-        `fs:${FILE}:read:extra`,
-        'fs:relative/path:read',
-        'fs:not-a-uuid:read',
-        // Another user's data.
-        `user:${OTHER}:email:read`,
-        `apps-of-user:${OTHER}:read`,
-        `subdomains-of-user:${OTHER}:write`,
-        `manage:kv-share:${OTHER}:${APP}:rooms`,
-        `manage:kv-share-read:${OTHER}:${APP}:rooms`,
-        `manage:kv-share-write:${OTHER}:${APP}:rooms`,
-        // Shape errors inside an allowed family.
-        `user:${ME}:email`,
-        `user:${ME}:email:write`,
-        `apps-of-user:${ME}`,
-        `apps-of-user:${ME}:manage`,
-        'app-data',
-        'app-data:',
-        `app-data:${APP}:sql:read`,
-        `app-data:${APP}:kv:flush`,
-        `app-data:${APP}:fs:get`,
-        `app-data:${APP}:kv:get:extra`,
-        'app-data:app-nope/:kv:read',
-        'app-data:not-an-app:kv:read',
-        `app-data:${APP}:`,
-        `app-data:${APP}:kv:`,
-        `app-data:${APP}::read`,
-        `app-root-dir:${APP}`,
-        `app-root-dir:${APP}:delete`,
-        'app-root-dir:not-an-app:read',
-        `app-root-dir:${APP}:read:extra`,
-        `apps-of-user:${ME}:read:extra`,
-        // Spelled other than canonically, which later checks would not match.
-        'f\\s:/x:read',
-        'fs:/alice/a\\b.txt:read',
-        `app-dat\\a:${APP}:kv:read`,
-        `app-root-di\\r:${APP}:read`,
-        `manag\\e:kv-share:${ME}:${APP}:rooms`,
-        `manage:kv-shar\\e:${ME}:${APP}:rooms`,
-        `manage:kv-share\\Crooms:${ME}:${APP}:abc`,
-        'event\\s:background',
-        `manage:kv-share:${ME}:${APP}`,
-        `manage:kv-share:${ME}:${APP}:rooms::abc`,
-        `manage:kv-share:${ME}:not-an-app:rooms`,
-        `manage:kv-share-read:${ME}:${APP}`,
-        `manage:kv-share-write:${ME}:${APP}:rooms::abc`,
-        `manage:kv-share-delete:${ME}:${APP}:rooms`,
-        // Prototype members are not families.
-        `constructor:${ME}:read`,
-        `manage:toString:${ME}:${APP}:rooms`,
-        'random-string',
-        '',
-    ])('refuses %s', (permission) => {
-        expect(parse(permission)).toBeNull();
-    });
-});

src/backend/services/permission/appGrantable.ts

@@ -1,198 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import { validate as validateUuid } from 'uuid';
-import {
-    APP_UID_SHAPE,
-    KV_SHARE_ACCESS_LEVELS,
-    type KvShareAccess,
-    kvShareRoot,
-} from '../kvShare/kvShares.js';
-import {
-    APP_DATA_CLASSES,
-    APP_DATA_KV_OPS,
-    APP_DATA_PERMISSION_PREFIX,
-    type AppDataStore,
-} from './appDataScopes.js';
-import { MANAGE_PERM_PREFIX } from './consts.js';
-import { PermissionUtil } from './permissionUtil.js';
-
-const ACCESS_LEVELS = ['read', 'write'] as const;
-type AccessLevel = (typeof ACCESS_LEVELS)[number];
-
-const FS_MODES = ['see', 'list', 'read', 'write'] as const;
-type FsMode = (typeof FS_MODES)[number];
-
-/**
- * A permission a user may grant an app through the consent prompt, parsed. No
- * app-actor check reads `apps-of-user:<uuid>:read` or `subdomains-of-user`;
- * they stay grantable because apps already request them.
- */
-export type AppGrantablePermission =
-    | { family: 'fs'; target: string; mode: FsMode }
-    | { family: 'email' }
-    | { family: 'apps' | 'subdomains'; access: AccessLevel }
-    | {
-          family: 'appData';
-          appUid: string;
-          store?: AppDataStore;
-          scope?: string;
-      }
-    | { family: 'appRootDir'; appUid: string; access: AccessLevel }
-    | {
-          family: 'kvShare';
-          level: KvShareAccess;
-          ownerUuid: string;
-          appUid: string;
-          segments: string[];
-      }
-    | { family: 'backgroundEvents' };
-
-/** One component as it is written canonically: `\` as `\\`, `:` as `\C`. */
-const escapeComponent = (component: string): string =>
-    component.replace(/\\/g, '\\\\').replace(/:/g, '\\C');
-
-const isOneOf = <T extends string>(
-    values: readonly T[],
-    value: string | undefined,
-): value is T =>
-    value !== undefined && (values as readonly string[]).includes(value);
-
-const ACCESS_FAMILIES: Record<string, 'apps' | 'subdomains'> = {
-    'apps-of-user': 'apps',
-    'subdomains-of-user': 'subdomains',
-};
-
-/** Own keys only, so `constructor` or `toString` never names a family. */
-const lookup = <T>(map: Record<string, T>, key: string | undefined) =>
-    key !== undefined && Object.hasOwn(map, key) ? map[key] : undefined;
-
-const parseAppData = (parts: string[]): AppGrantablePermission | null => {
-    const [, appUid, store, scope, ...rest] = parts;
-    if (!appUid || !APP_UID_SHAPE.test(appUid) || rest.length > 0) return null;
-    if (store === undefined) return { family: 'appData', appUid };
-    if (store === 'kv') {
-        if (
-            scope !== undefined &&
-            !isOneOf(APP_DATA_CLASSES, scope) &&
-            !isOneOf(APP_DATA_KV_OPS, scope)
-        ) {
-            return null;
-        }
-    } else if (store === 'fs') {
-        if (scope !== undefined && !isOneOf(APP_DATA_CLASSES, scope)) {
-            return null;
-        }
-    } else {
-        return null;
-    }
-    return { family: 'appData', appUid, store, scope };
-};
-
-/**
- * `permission` as an app-grantable permission, or null when a user may not
- * grant it to an app. Families naming a user (email, apps, subdomains, share
- * delegation) must name `userUuid`, the user granting it.
- */
-export const parseAppGrantablePermission = (
-    permission: string,
-    userUuid: string,
-): AppGrantablePermission | null => {
-    if (permission === 'events:background') {
-        return { family: 'backgroundEvents' };
-    }
-
-    const parts = PermissionUtil.split(permission);
-    // Checks that run on the raw string, after this one, match only the
-    // canonical spelling, so `f\s:` must not reach them as `fs:`.
-    if (parts.map(escapeComponent).join(':') !== permission) return null;
-    const [head] = parts;
-
-    if (head === 'fs') {
-        const [, target, mode] = parts;
-        if (parts.length !== 3 || !target || !isOneOf(FS_MODES, mode)) {
-            return null;
-        }
-        if (!target.startsWith('/') && !validateUuid(target)) return null;
-        return { family: 'fs', target, mode };
-    }
-
-    if (head === 'user') {
-        const [, uuid, field, mode] = parts;
-        if (
-            parts.length !== 4 ||
-            uuid !== userUuid ||
-            field !== 'email' ||
-            mode !== 'read'
-        ) {
-            return null;
-        }
-        return { family: 'email' };
-    }
-
-    const accessFamily = lookup(ACCESS_FAMILIES, head);
-    if (accessFamily) {
-        const [, uuid, access] = parts;
-        if (
-            parts.length !== 3 ||
-            uuid !== userUuid ||
-            !isOneOf(ACCESS_LEVELS, access)
-        ) {
-            return null;
-        }
-        return { family: accessFamily, access };
-    }
-
-    if (head === APP_DATA_PERMISSION_PREFIX) return parseAppData(parts);
-
-    if (head === 'app-root-dir') {
-        const [, appUid, access] = parts;
-        if (
-            parts.length !== 3 ||
-            !appUid ||
-            !APP_UID_SHAPE.test(appUid) ||
-            !isOneOf(ACCESS_LEVELS, access)
-        ) {
-            return null;
-        }
-        return { family: 'appRootDir', appUid, access };
-    }
-
-    const level =
-        head === MANAGE_PERM_PREFIX
-            ? KV_SHARE_ACCESS_LEVELS.find(
-                  (access) => kvShareRoot(access) === parts[1],
-              )
-            : undefined;
-    if (level) {
-        const [, , ownerUuid, appUid, ...segments] = parts;
-        if (
-            ownerUuid !== userUuid ||
-            !appUid ||
-            !APP_UID_SHAPE.test(appUid) ||
-            segments.length === 0 ||
-            segments.some((segment) => segment === '')
-        ) {
-            return null;
-        }
-        return { family: 'kvShare', level, ownerUuid, appUid, segments };
-    }
-
-    return null;
-};

src/backend/services/permission/permissionUtil.ts

@@ -211,11 +211,6 @@ export interface ImplicatorCheckInput {
     actor: Actor;
     permission: string;
     recurse?: (actor: Actor, permission: string) => Promise<ReadingNode[]>;
-    /**
-     * Shared by every implicator call of one scan, so a rule can answer the
-     * options of one check from a single lookup. Never outlives the scan.
-     */
-    memo?: Map<string, unknown>;
 }
 
 export interface PermissionImplicator {

src/backend/services/share/ShareNotificationService.ts

@@ -43,8 +43,7 @@ import {
 } from './shareDeepLink';
 import { NOTIFY_FANOUT_CAP } from '../../core/teams.js';
 import { abuseKey, cleanEmail, isBlockedEmail } from '../../util/email.js';
-import { blocksAllShares } from './shareBlocks.js';
-import type { ResolvedShare } from './ShareService';
+import { blocksAllShares, type ResolvedShare } from './ShareService';
 import { withRedisLock } from '../../util/redisLock.js';
 
 /**

src/backend/services/share/ShareService.test.ts

@@ -2469,52 +2469,6 @@ describe('ShareService', () => {
             );
         });
 
-        it('files a recipient leaving under the issuer, naming who acted', async () => {
-            const owner = await makeUser();
-            const recipient = await makeUser();
-            const file = await makeFile(owner.user);
-            await share(owner.actor, {
-                uid: file.uuid,
-                recipient: { email: recipient.email },
-                mode: 'read',
-            });
-            await unshare(recipient.actor, {
-                uid: file.uuid,
-                recipient: { email: recipient.email },
-            });
-
-            const rows = await vi.waitFor(async () => {
-                const found = await server.clients.db.read(
-                    'SELECT `issuer_user_id`, `extra` FROM `audit_user_to_user_permissions` ' +
-                        'WHERE `holder_user_id` = ? AND `action` = ?',
-                    [recipient.user.id, 'revoke'],
-                );
-                expect(found.length).toBeGreaterThan(0);
-                return found;
-            });
-            for (const row of rows) {
-                expect(Number(row.issuer_user_id)).toBe(owner.user.id);
-                const extra =
-                    typeof row.extra === 'string'
-                        ? JSON.parse(row.extra)
-                        : row.extra;
-                expect(extra?.actingUserId).toBe(recipient.user.id);
-            }
-
-            const ownerTrail = await audit(owner.actor, { uid: file.uuid });
-            expect(
-                ownerTrail.items.some(
-                    (i) =>
-                        i.action === 'revoke' &&
-                        i.issuer.username === owner.user.username,
-                ),
-            ).toBe(true);
-            const recipientTrail = await audit(recipient.actor);
-            expect(
-                recipientTrail.items.some((i) => i.entryUid === file.uuid),
-            ).toBe(false);
-        });
-
         it('lists what the caller granted when no item is named', async () => {
             const owner = await makeUser();
             const other = await makeUser();

src/backend/services/share/ShareService.ts

@@ -59,14 +59,7 @@ import { carriesClosedAppData } from '../permission/appDataScopes';
 import { MANAGE_PERM_PREFIX } from '../permission/consts';
 import { PermissionUtil } from '../permission/permissionUtil.js';
 import { SubscriptionCache } from '../events/subscriptionCache.js';
-import { KV_SHARE_ACCESS_LEVELS, kvShareRoot } from '../kvShare/kvShares.js';
 import { PuterService } from '../types';
-import {
-    BLOCK_ALL_SHARES_KEY,
-    blocksAllShares,
-    recipientNotAcceptingShares,
-    refusesSharesFrom,
-} from './shareBlocks.js';
 
 // -- Types ------------------------------------------------------------
 
@@ -295,6 +288,21 @@ const RETIRE_CHUNK_SIZE = 100;
 /** Shares one user may create per UTC day, absent a config override. */
 export const DEFAULT_DAILY_SHARE_LIMIT = 200;
 
+/**
+ * Where "refuse shares from everyone" lives on the user row.
+ *
+ * A key in the existing `metadata` blob rather than a column of its own: the
+ * share path already holds the recipient's row by the time it asks, so reading
+ * it costs nothing either way, and a one-bit preference doesn't earn a
+ * migration per dialect.
+ */
+const BLOCK_ALL_SHARES_KEY = 'blockAllShares';
+
+/** Whether this account refuses shares from everyone. */
+export const blocksAllShares = (
+    user: Pick<UserRow, 'metadata'> | null,
+): boolean => Boolean(user?.metadata?.[BLOCK_ALL_SHARES_KEY]);
+
 /**
  * What a share recipient's browser is told about someone else's entry.
  *
@@ -2309,19 +2317,13 @@ export class ShareService extends PuterService {
     }> {
         const userId = this.#requireUserId(actor);
 
-        // A key-value share's grant names its owner and prefix, which its
-        // holder is never told, so only the owner sees those rows.
-        const ownedRoots = {
-            roots: KV_SHARE_ACCESS_LEVELS.map(kvShareRoot),
-            ownerUuid: actor.user.uuid ?? '',
-        };
         let filter: UserUserAuditFilter;
         if (target.uid || target.path) {
             const entry = await this.#resolveEntry(target, actor);
             await this.#assertCanManage(actor, entry);
-            filter = { permissions: entryPermissions(entry.uuid), ownedRoots };
+            filter = { permissions: entryPermissions(entry.uuid) };
         } else {
-            filter = { issuerUserId: userId, ownedRoots };
+            filter = { issuerUserId: userId };
         }
 
         const page = await this.stores.permission.listUserUserAudit(filter, {
@@ -2725,8 +2727,13 @@ export class ShareService extends PuterService {
      * switch is free; only a caller who cleared it pays for the pair lookup.
      */
     async #assertNotBlocked(issuer: number, holder: UserRow): Promise<void> {
-        if (await refusesSharesFrom(this.stores.userBlock, holder, issuer))
-            throw recipientNotAcceptingShares();
+        const blocked =
+            blocksAllShares(holder) ||
+            (await this.stores.userBlock.isBlocked(holder.id, issuer));
+        if (!blocked) return;
+        throw new HttpError(403, 'recipient is not accepting shares', {
+            legacyCode: 'recipient_not_accepting_shares',
+        });
     }
 
     // -- Internals ----------------------------------------------------
@@ -2794,11 +2801,11 @@ export class ShareService extends PuterService {
                 // stopped accepting shares — from this sender, or from anyone
                 // — since it was sent.
                 if (
-                    await refusesSharesFrom(
-                        this.stores.userBlock,
-                        holder,
+                    blocksAllShares(holder) ||
+                    (await this.stores.userBlock.isBlocked(
+                        holderUserId,
                         Number(row.issuer_user_id),
-                    )
+                    ))
                 ) {
                     await this.stores.share.deleteByUid(row.uid);
                     continue;

src/backend/services/share/shareBlocks.ts

@@ -1,58 +0,0 @@
-/*
- * Copyright (C) 2024-present Puter Technologies Inc.
- *
- * This file is part of Puter.
- *
- * Puter is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-import { HttpError } from '../../core/http/HttpError.js';
-import type { UserRow } from '../../stores/user/UserStore.js';
-import type { UserBlockStore } from '../../stores/userBlock/UserBlockStore.js';
-
-/**
- * Where "refuse shares from everyone" lives on the user row.
- *
- * A key in the existing `metadata` blob rather than a column of its own: the
- * share path already holds the recipient's row by the time it asks, so reading
- * it costs nothing either way, and a one-bit preference doesn't earn a
- * migration per dialect.
- */
-export const BLOCK_ALL_SHARES_KEY = 'blockAllShares';
-
-/** Whether this account refuses shares from everyone. */
-export const blocksAllShares = (
-    user: Pick<UserRow, 'metadata'> | null,
-): boolean => Boolean(user?.metadata?.[BLOCK_ALL_SHARES_KEY]);
-
-/**
- * Whether `holder` refuses shares from `issuerId`: from everyone, or from that
- * sender. The blanket switch is on the row already in hand, so only a holder
- * who cleared it costs the pair lookup.
- */
-export const refusesSharesFrom = async (
-    userBlock: Pick<UserBlockStore, 'isBlocked'>,
-    holder: Pick<UserRow, 'id' | 'metadata'>,
-    issuerId: number,
-): Promise<boolean> =>
-    blocksAllShares(holder) || (await userBlock.isBlocked(holder.id, issuerId));
-
-/**
- * Refusing everyone and refusing this sender read the same: which of the two it
- * is is the recipient's business, not the sender's.
- */
-export const recipientNotAcceptingShares = (): HttpError =>
-    new HttpError(403, 'recipient is not accepting shares', {
-        legacyCode: 'recipient_not_accepting_shares',
-    });

src/backend/services/user/UserAccountService.ts

@@ -27,9 +27,6 @@ import { PuterService } from '../types.js';
  */
 const PROVISIONED_FSENTRY_COUNT = 8;
 
-/** Apps read per page when listing the ones an account owns. */
-const OWNED_APPS_PAGE = 500;
-
 /**
  * Account-lifecycle operations that more than one caller needs: deleting an
  * account and everything hanging off it, and measuring whether an account has
@@ -104,16 +101,8 @@ export class UserAccountService extends PuterService {
             console.warn('[cascade-delete-user] subdomain cleanup failed:', e);
         }
 
-        // The user's apps cascade away with the row, with no `app.changed`, so
-        // `user.delete` names them for what was tied to them.
-        let appUids: string[] = [];
-        try {
-            appUids = await this.#ownedAppUids(userId);
-        } catch (e) {
-            console.warn('[cascade-delete-user] owned-app lookup failed:', e);
-        }
-        // Record them first so a hosted origin doesn't hand their uids to the
-        // subdomain's next owner.
+        // The user's apps cascade away with the row; record them first so a
+        // hosted origin doesn't hand their uids to the subdomain's next owner.
         await this.stores.app.recordDeletedForOwner(userId);
         // Other users' sites and workers tied to those apps cascade too.
         const appSites = await this.stores.subdomain.listAppCascade({
@@ -154,7 +143,6 @@ export class UserAccountService extends PuterService {
                     user_id: userId,
                     user_uuid: userUuid,
                     stripe_customer_id: stripeCustomerId,
-                    appUids,
                 },
                 {},
             );
@@ -176,22 +164,6 @@ export class UserAccountService extends PuterService {
         }
     }
 
-    /** The uids of every app this user owns, a page at a time. */
-    async #ownedAppUids(userId: number): Promise<string[]> {
-        const uids: string[] = [];
-        let afterId: number | undefined;
-        for (;;) {
-            const apps = (await this.stores.app.list({
-                ownerUserId: userId,
-                afterId,
-                limit: OWNED_APPS_PAGE,
-            })) as Array<{ id: number; uid: string }>;
-            uids.push(...apps.map((app) => app.uid));
-            if (apps.length < OWNED_APPS_PAGE) return uids;
-            afterId = apps[apps.length - 1]!.id;
-        }
-    }
-
     /**
      * Delete the user's sites one by one, emitting `subdomain.delete` for each
      * as the driver does. The FK cascade would drop the rows silently, leaving

src/backend/stores/app/AppStore.js

@@ -520,7 +520,6 @@ export class AppStore extends PuterStore {
      * @param {number} [filters.ownerUserId] — only apps owned by this user
      * @param {number} [filters.appOwner] — only apps created by another app
      * @param {string} [filters.name] — exact name match
-     * @param {number} [filters.afterId] — only apps with a greater `id`
      * @param {number} [filters.limit=500] Default is `500`
      */
     async list(filters = {}) {

src/backend/stores/events/KvShareHandleStore.integration.test.ts

@@ -20,9 +20,9 @@
 /**
  * The store's own guard against a row wider than the column that holds it.
  *
- * `KvShareService.mintKvHandle` already bounds `keyPrefix` and `permission`
- * well under these widths before the store ever sees them, so reaching the
- * guard here means calling the store directly.
+ * `EventsService.mintKvHandle` already bounds `keyPrefix` and `permission` well
+ * under these widths before the store ever sees them, so reaching the guard
+ * here means calling the store directly.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
@@ -128,134 +128,3 @@ describe('the owner listing', () => {
         expect(second.cursor).toBeUndefined();
     });
 });
-
-describe('retiring an app`s handles', () => {
-    it('works through them a batch at a time, as the platform', async () => {
-        const appUid = 'app-retire-batches';
-        const minted = [];
-        for (let i = 0; i < 3; i++)
-            minted.push(
-                await store().mint(
-                    input({
-                        appUid,
-                        keyPrefix: `batch-${i}:`,
-                        permission: `kv-share:owner-uuid:${appUid}:batch-${i}`,
-                    }),
-                ),
-            );
-
-        const batches: number[] = [];
-        for (;;) {
-            const batch = await store().listLiveForApps([appUid], 2);
-            batches.push(batch.length);
-            if (batch.length === 0) break;
-            await store().retireMany(
-                batch.map((row) => row.handle),
-                'system',
-            );
-        }
-        expect(batches).toEqual([2, 1, 0]);
-        for (const { handle } of minted)
-            expect(await store().getByHandle(handle)).toMatchObject({
-                revokedBy: 'system',
-                revokedAt: expect.any(Number),
-            });
-    });
-});
-
-describe('changing a live handle', () => {
-    it('never brings a retired one back', async () => {
-        const row = await store().mint(input({ keyPrefix: 'cas:' }));
-        await store().retire(row.handle, ownerUserId);
-        const after = await store().update(row.handle, ownerUserId, {
-            permission: 'kv-share-write:owner-uuid:app-column-widths:cas',
-            label: 'late',
-        });
-        expect(after).toMatchObject({
-            revokedAt: expect.any(Number),
-            permission: row.permission,
-            label: null,
-        });
-    });
-
-    it('is scoped to the owner', async () => {
-        const row = await store().mint(input({ keyPrefix: 'scoped:' }));
-        expect(
-            await store().update(row.handle, granteeUserId, { label: 'x' }),
-        ).toBeNull();
-        expect((await store().getByHandle(row.handle))?.label).toBeNull();
-    });
-});
-
-describe('finding the live handle on a region', () => {
-    it('matches the prefix byte for byte, and reports one that differs only in case', async () => {
-        const appUid = `app-case-${Date.now().toString(36)}`;
-        const region = { ownerUserId, granteeUserId, appUid };
-        const minted = await store().mint(
-            input({
-                appUid,
-                keyPrefix: 'Notes:',
-                permission: `kv-share:o:${appUid}:Notes`,
-            }),
-        );
-
-        expect(
-            await store().findLive({ ...region, keyPrefix: 'Notes:' }),
-        ).toMatchObject({ handle: minted.handle });
-        expect(
-            await store().findLive({ ...region, keyPrefix: 'notes:' }),
-        ).toBeNull();
-        expect(
-            await store().hasLiveCaseVariant({
-                ...region,
-                keyPrefix: 'notes:',
-            }),
-        ).toBe(true);
-        expect(
-            await store().hasLiveCaseVariant({
-                ...region,
-                keyPrefix: 'Notes:',
-            }),
-        ).toBe(false);
-        expect(
-            await store().hasLiveCaseVariant({
-                ...region,
-                keyPrefix: 'other:',
-            }),
-        ).toBe(false);
-
-        await store().retire(minted.handle, ownerUserId);
-        expect(
-            await store().hasLiveCaseVariant({
-                ...region,
-                keyPrefix: 'notes:',
-            }),
-        ).toBe(false);
-    });
-});
-
-describe('the holder listing', () => {
-    it('carries no owner, prefix or grant string', async () => {
-        const row = await store().mint(
-            input({
-                appUid: 'app-holder-listing',
-                keyPrefix: 'secret-prefix:',
-                permission:
-                    'kv-share-read:owner-uuid:app-holder-listing:secret-prefix',
-                label: 'Shown',
-            }),
-        );
-        const page = await store().listLiveForGrantee(granteeUserId, {
-            appUid: 'app-holder-listing',
-        });
-        expect(page.items).toEqual([
-            {
-                handle: row.handle,
-                appUid: 'app-holder-listing',
-                access: 'read',
-                label: 'Shown',
-                createdAt: row.createdAt,
-            },
-        ]);
-    });
-});

src/backend/stores/events/KvShareHandleStore.ts

@@ -17,13 +17,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import {
-    KV_SHARE_ACCESS_LEVELS,
-    kvShareRoot,
-    mintKvHandleId,
-    type KvShareAccess,
-} from '../../services/kvShare/kvShares.js';
-import { BoundedTtlMap } from '../../util/boundedTtlMap.js';
+import { mintKvHandleId } from '../../services/events/kvShares.js';
 import {
     keysetPage,
     openIdCursor,
@@ -46,11 +40,6 @@ const TABLE = 'kv_share_handles';
 export const KV_HANDLE_LIST_DEFAULT_LIMIT = 50;
 export const KV_HANDLE_LIST_LIMIT_CAP = 200;
 
-/** Who retired a handle: its owner, its holder, or the platform. */
-export type KvShareRevokedBy = 'owner' | 'holder' | 'system';
-
-const REVOKED_BY: readonly KvShareRevokedBy[] = ['owner', 'holder', 'system'];
-
 export interface KvShareHandle {
     handle: string;
     ownerUserId: number;
@@ -58,39 +47,10 @@ export interface KvShareHandle {
     appUid: string;
     /** The granted root, ending on the key delimiter. */
     keyPrefix: string;
-    /** The user-to-user grant this handle mirrors; its root is the level. */
+    /** The user-to-user grant this handle mirrors. */
     permission: string;
-    /** Owner-set text the holder is shown, or `null`. */
-    label: string | null;
     createdAt: number;
     revokedAt: number | null;
-    /** `null` while live, and on rows retired before this was recorded. */
-    revokedBy: KvShareRevokedBy | null;
-}
-
-/** A live handle as the hot path needs it: the row and its owner's state. */
-export interface LiveKvShareHandle {
-    row: Omit<KvShareHandle, 'label'>;
-    ownerUuid: string;
-    ownerSuspended: boolean;
-}
-
-/**
- * A handle as its holder may know it. Selected without the owner, the prefix or
- * the grant string, so none of them can reach a holder-facing response.
- */
-export interface HeldKvShareHandle {
-    handle: string;
-    appUid: string;
-    access: KvShareAccess;
-    label: string | null;
-    createdAt: number;
-}
-
-/** What a level or label change writes; an absent field is left alone. */
-export interface KvShareHandleUpdate {
-    permission?: string;
-    label?: string | null;
 }
 
 export interface KvShareHandleListOptions {
@@ -107,7 +67,6 @@ export interface MintKvShareHandleInput {
     appUid: string;
     keyPrefix: string;
     permission: string;
-    label?: string | null;
 }
 
 export interface FindLiveKvShareHandleInput {
@@ -117,21 +76,8 @@ export interface FindLiveKvShareHandleInput {
     keyPrefix: string;
 }
 
-/** Handle cache bounds: live rows, and recently missed names. */
-const LIVE_CACHE_TTL_MS = 60_000;
-const MISS_CACHE_TTL_MS = 5_000;
-const LIVE_CACHE_MAX_ENTRIES = 10_000;
-
-/** Rows one app-deletion retire pass takes. */
-export const KV_HANDLE_RETIRE_BATCH = 500;
-
 const nowSeconds = (): number => Math.floor(Date.now() / 1000);
 
-const toRevokedBy = (value: unknown): KvShareRevokedBy | null =>
-    REVOKED_BY.includes(value as KvShareRevokedBy)
-        ? (value as KvShareRevokedBy)
-        : null;
-
 const toRow = (row: Record<string, unknown>): KvShareHandle => ({
     handle: String(row.handle),
     ownerUserId: Number(row.owner_user_id),
@@ -139,50 +85,15 @@ const toRow = (row: Record<string, unknown>): KvShareHandle => ({
     appUid: String(row.app_uid),
     keyPrefix: String(row.key_prefix),
     permission: String(row.permission),
-    label:
-        row.label === null || row.label === undefined
-            ? null
-            : String(row.label),
     createdAt: Number(row.created_at) || 0,
     revokedAt: row.revoked_at === null ? null : Number(row.revoked_at),
-    revokedBy: toRevokedBy(row.revoked_by),
 });
 
 const SELECT_COLUMNS =
     '`handle`, `owner_user_id`, `grantee_user_id`, `app_uid`, ' +
-    '`key_prefix`, `permission`, `label`, `created_at`, `revoked_at`, ' +
-    '`revoked_by`';
-
-/**
- * The level as SQL reads it off the grant's root, so the holder listing can
- * report it without selecting the grant string itself.
- */
-const ACCESS_COLUMN =
-    `CASE WHEN \`permission\` LIKE '${kvShareRoot('write')}:%' THEN 'write' ` +
-    `WHEN \`permission\` LIKE '${kvShareRoot('read')}:%' THEN 'read' ` +
-    "ELSE 'watch' END AS `access`";
-
-const toAccess = (value: unknown): KvShareAccess =>
-    KV_SHARE_ACCESS_LEVELS.includes(value as KvShareAccess)
-        ? (value as KvShareAccess)
-        : 'watch';
-
-const clampLimit = (limit: number | undefined): number =>
-    Math.min(
-        Math.max(1, Math.floor(limit ?? KV_HANDLE_LIST_DEFAULT_LIMIT)),
-        KV_HANDLE_LIST_LIMIT_CAP,
-    );
+    '`key_prefix`, `permission`, `created_at`, `revoked_at`';
 
 export class KvShareHandleStore extends PuterStore {
-    readonly #live = new BoundedTtlMap<string, LiveKvShareHandle>({
-        maxEntries: LIVE_CACHE_MAX_ENTRIES,
-        ttlMs: LIVE_CACHE_TTL_MS,
-    });
-    readonly #missing = new BoundedTtlMap<string, true>({
-        maxEntries: LIVE_CACHE_MAX_ENTRIES,
-        ttlMs: MISS_CACHE_TTL_MS,
-    });
-
     async mint(input: MintKvShareHandleInput): Promise<KvShareHandle> {
         const row: KvShareHandle = {
             handle: mintKvHandleId(),
@@ -191,10 +102,8 @@ export class KvShareHandleStore extends PuterStore {
             appUid: input.appUid,
             keyPrefix: input.keyPrefix,
             permission: input.permission,
-            label: input.label ?? null,
             createdAt: nowSeconds(),
             revokedAt: null,
-            revokedBy: null,
         };
         assertColumnWidths(KV_SHARE_HANDLE_WIDTHS, {
             handle: row.handle,
@@ -210,56 +119,12 @@ export class KvShareHandleStore extends PuterStore {
             app_uid: row.appUid,
             key_prefix: row.keyPrefix,
             permission: row.permission,
-            label: row.label,
             created_at: row.createdAt,
             revoked_at: null,
         });
-        this.#forget(row.handle);
         return row;
     }
 
-    /**
-     * A live handle and its owner's state, cached in-process (hits up to 60 s,
-     * misses 5 s). Authority is the grant, checked on every call, so a stale
-     * row only keeps an address alive a little longer, never widens it.
-     */
-    async getLive(handle: string): Promise<LiveKvShareHandle | null> {
-        const cached = this.#live.get(handle);
-        if (cached) return cached;
-        if (this.#missing.has(handle)) return null;
-
-        const query =
-            'SELECT h.`handle`, h.`owner_user_id`, h.`grantee_user_id`, ' +
-            'h.`app_uid`, h.`key_prefix`, h.`permission`, h.`created_at`, ' +
-            'h.`revoked_at`, h.`revoked_by`, ' +
-            'u.`uuid` AS `owner_uuid`, u.`suspended` AS `owner_suspended` ' +
-            `FROM \`${TABLE}\` h JOIN \`user\` u ON u.\`id\` = h.\`owner_user_id\` ` +
-            'WHERE h.`handle` = ?';
-        let rows = await this.clients.db.read(query, [handle]);
-        if (rows.length === 0)
-            rows = await this.clients.db.pread(query, [handle]);
-
-        const found = rows[0];
-        if (!found || found.revoked_at !== null || !found.owner_uuid) {
-            this.#missing.set(handle, true);
-            return null;
-        }
-        const { label: _label, ...row } = toRow({ ...found, label: null });
-        const live: LiveKvShareHandle = {
-            row,
-            ownerUuid: String(found.owner_uuid),
-            ownerSuspended: Boolean(Number(found.owner_suspended ?? 0)),
-        };
-        this.#live.set(handle, live);
-        return live;
-    }
-
-    /** Drops this node's cached copy; other nodes converge within the TTL. */
-    #forget(handle: string): void {
-        this.#live.delete(handle);
-        this.#missing.delete(handle);
-    }
-
     /**
      * Live handles this owner is holding out — in total, and in the namespace a
      * mint is naming. Both ceilings read off one count, over the owner index.
@@ -290,17 +155,10 @@ export class KvShareHandleStore extends PuterStore {
     async findLive(
         input: FindLiveKvShareHandleInput,
     ): Promise<KvShareHandle | null> {
-        // Byte-exact, so `Notes:` and `notes:` are two regions everywhere. The
-        // collation goes on the utf8mb4 column, so the connection's charset
-        // doesn't matter.
-        const exactPrefix = this.clients.db.case({
-            mysql: '`key_prefix` COLLATE utf8mb4_bin = ?',
-            otherwise: '`key_prefix` = ?',
-        });
         const rows = await this.clients.db.pread(
             `SELECT ${SELECT_COLUMNS} FROM \`${TABLE}\` WHERE ` +
                 '`owner_user_id` = ? AND `grantee_user_id` = ? AND ' +
-                `\`app_uid\` = ? AND ${exactPrefix} AND \`revoked_at\` IS NULL ` +
+                '`app_uid` = ? AND `key_prefix` = ? AND `revoked_at` IS NULL ' +
                 'LIMIT 1',
             [
                 input.ownerUserId,
@@ -312,34 +170,10 @@ export class KvShareHandleStore extends PuterStore {
         return rows.length > 0 ? toRow(rows[0]) : null;
     }
 
-    /**
-     * Whether a live handle for the same owner, grantee and app has a prefix
-     * equal to this one ignoring case but not byte-equal: a grant on it would
-     * collide with this one's where the database compares case-insensitively.
-     */
-    async hasLiveCaseVariant(
-        input: FindLiveKvShareHandleInput,
-    ): Promise<boolean> {
-        const rows = await this.clients.db.pread(
-            `SELECT \`key_prefix\` FROM \`${TABLE}\` WHERE ` +
-                '`owner_user_id` = ? AND `grantee_user_id` = ? AND ' +
-                '`app_uid` = ? AND LOWER(`key_prefix`) = LOWER(?) AND ' +
-                // At most one live row is byte-exact, so two find a variant.
-                '`revoked_at` IS NULL LIMIT 2',
-            [
-                input.ownerUserId,
-                input.granteeUserId,
-                input.appUid,
-                input.keyPrefix,
-            ],
-        );
-        return rows.some((row) => String(row.key_prefix) !== input.keyPrefix);
-    }
-
     /**
      * Every live handle this owner holds out to one grantee, across every
-     * region — what a revoke or an unshare walks to find the narrower handles
-     * that go with a wider one. Bounded by the per-account handle cap.
+     * region — what a revoke walks to find a narrower handle whose grant just
+     * died as a side effect of a wider one being withdrawn.
      */
     async listLiveForOwnerAndGrantee(
         ownerUserId: number,
@@ -372,173 +206,32 @@ export class KvShareHandleStore extends PuterStore {
      * unknown handle and somebody else's both get, so retiring cannot be used
      * to find out that a handle exists.
      *
-     * Idempotent: an already-retired handle keeps the timestamp it has, so a
-     * retry after a failed step is safe.
+     * Idempotent: an already-retired handle keeps the timestamp it has. The
+     * caller withdraws the grant first and that step can fail, so this one has
+     * to be safe to reach twice.
+     *
+     * The `revoked_at IS NULL` predicate makes the read-then-write a
+     * compare-and-set: two callers racing means one stamps the row and the
+     * other reports the stamp it found, rather than both writing.
      */
     async retire(
         handle: string,
         ownerUserId: number,
-        revokedBy: 'owner' | 'system' = 'owner',
     ): Promise<KvShareHandle | null> {
-        await this.retireMany([handle], revokedBy, { ownerUserId });
-        const row = await this.getByHandle(handle);
-        return row?.ownerUserId === ownerUserId ? row : null;
-    }
+        const existing = await this.getByHandle(handle);
+        if (!existing || existing.ownerUserId !== ownerUserId) return null;
+        if (existing.revokedAt !== null) return existing;
 
-    /** {@link retire}, scoped to the holder instead, recorded as theirs. */
-    async retireAsHolder(
-        handle: string,
-        granteeUserId: number,
-    ): Promise<KvShareHandle | null> {
-        await this.retireMany([handle], 'holder', { granteeUserId });
-        const row = await this.getByHandle(handle);
-        return row?.granteeUserId === granteeUserId ? row : null;
-    }
-
-    /**
-     * Retire several handles in one statement, optionally scoped to their owner
-     * or holder. A compare-and-set on `revoked_at IS NULL`, so a handle already
-     * retired keeps its timestamp and who retired it.
-     */
-    async retireMany(
-        handles: readonly string[],
-        revokedBy: KvShareRevokedBy,
-        scope: { ownerUserId?: number; granteeUserId?: number } = {},
-    ): Promise<void> {
-        const unique = [...new Set(handles)];
-        if (unique.length === 0) return;
-        const where = [
-            `\`handle\` IN (${unique.map(() => '?').join(', ')})`,
-            '`revoked_at` IS NULL',
-        ];
-        const params: unknown[] = [nowSeconds(), revokedBy, ...unique];
-        if (scope.ownerUserId !== undefined) {
-            where.push('`owner_user_id` = ?');
-            params.push(scope.ownerUserId);
-        }
-        if (scope.granteeUserId !== undefined) {
-            where.push('`grantee_user_id` = ?');
-            params.push(scope.granteeUserId);
-        }
-        await this.clients.db.write(
-            `UPDATE \`${TABLE}\` SET \`revoked_at\` = ?, \`revoked_by\` = ? ` +
-                `WHERE ${where.join(' AND ')}`,
-            params,
+        const at = nowSeconds();
+        const result = await this.clients.db.write(
+            `UPDATE \`${TABLE}\` SET \`revoked_at\` = ? ` +
+                'WHERE `handle` = ? AND `owner_user_id` = ? ' +
+                'AND `revoked_at` IS NULL',
+            [at, handle, ownerUserId],
         );
-        for (const handle of unique) this.#forget(handle);
-    }
-
-    /**
-     * One batch of live handles in these apps' namespaces, oldest first. A
-     * deleted app's handles are retired off this; the caller repeats until a
-     * batch comes back short.
-     */
-    async listLiveForApps(
-        appUids: readonly string[],
-        limit = KV_HANDLE_RETIRE_BATCH,
-    ): Promise<KvShareHandle[]> {
-        const unique = [...new Set(appUids)];
-        if (unique.length === 0) return [];
-        const rows = await this.clients.db.pread(
-            `SELECT ${SELECT_COLUMNS} FROM \`${TABLE}\` ` +
-                `WHERE \`app_uid\` IN (${unique.map(() => '?').join(', ')}) ` +
-                'AND `revoked_at` IS NULL ORDER BY `id` LIMIT ?',
-            [...unique, limit],
-        );
-        return rows.map(toRow);
-    }
-
-    /**
-     * Change a live handle's level or label in place, scoped to its owner. A
-     * compare-and-set on `revoked_at IS NULL`, so a handle retired meanwhile
-     * stays retired; returns the row as it now stands, or `null` for none.
-     */
-    async update(
-        handle: string,
-        ownerUserId: number,
-        changes: KvShareHandleUpdate,
-    ): Promise<KvShareHandle | null> {
-        const sets: string[] = [];
-        const params: unknown[] = [];
-        if (changes.permission !== undefined) {
-            assertColumnWidths(KV_SHARE_HANDLE_WIDTHS, {
-                permission: changes.permission,
-            });
-            sets.push('`permission` = ?');
-            params.push(changes.permission);
-        }
-        if (changes.label !== undefined) {
-            sets.push('`label` = ?');
-            params.push(changes.label);
-        }
-        if (sets.length > 0) {
-            await this.clients.db.write(
-                `UPDATE \`${TABLE}\` SET ${sets.join(', ')} ` +
-                    'WHERE `handle` = ? AND `owner_user_id` = ? ' +
-                    'AND `revoked_at` IS NULL',
-                [...params, handle, ownerUserId],
-            );
-        }
-        this.#forget(handle);
-        const row = await this.getByHandle(handle);
-        return row && row.ownerUserId === ownerUserId ? row : null;
-    }
-
-    /**
-     * Live handles held by one user, newest grants last, keyset-paginated on
-     * the grantee index. Selected without the owner, prefix or grant string:
-     * this is the holder's listing, and none of those are theirs to see.
-     */
-    async listLiveForGrantee(
-        granteeUserId: number,
-        options: KvShareHandleListOptions = {},
-    ): Promise<PageResult<HeldKvShareHandle>> {
-        const limit = clampLimit(options.limit);
-        const after = openIdCursor(options.cursor, this.config.jwt_secret_v2);
-
-        const filter = ['`grantee_user_id` = ?', '`revoked_at` IS NULL'];
-        const filterParams: unknown[] = [granteeUserId];
-        if (options.appUid !== undefined && options.appUid !== null) {
-            filter.push('`app_uid` = ?');
-            filterParams.push(options.appUid);
-        }
-        const where = [...filter];
-        const params = [...filterParams];
-        if (after !== null) {
-            where.push('`id` > ?');
-            params.push(after);
-        }
-
-        const rows = await this.clients.db.read(
-            'SELECT `id`, `handle`, `app_uid`, `label`, `created_at`, ' +
-                `${ACCESS_COLUMN} FROM \`${TABLE}\` ` +
-                `WHERE ${where.join(' AND ')} ORDER BY \`id\` LIMIT ?`,
-            [...params, limit + 1],
-        );
-        const page = keysetPage(rows, limit, this.config.jwt_secret_v2);
-        const result: PageResult<HeldKvShareHandle> = {
-            items: page.rows.map((row) => ({
-                handle: String(row.handle),
-                appUid: String(row.app_uid),
-                access: toAccess(row.access),
-                label:
-                    row.label === null || row.label === undefined
-                        ? null
-                        : String(row.label),
-                createdAt: Number(row.created_at) || 0,
-            })),
-        };
-        if (page.cursor) result.cursor = page.cursor;
-
-        if (options.includeTotal) {
-            const [count] = await this.clients.db.read(
-                `SELECT COUNT(*) AS \`total\` FROM \`${TABLE}\` ` +
-                    `WHERE ${filter.join(' AND ')}`,
-                filterParams,
-            );
-            result.total = Number(count?.total ?? 0);
-        }
-        return result;
+        if (result?.anyRowsAffected === false)
+            return await this.getByHandle(handle);
+        return { ...existing, revokedAt: at };
     }
 
     /**
@@ -549,7 +242,13 @@ export class KvShareHandleStore extends PuterStore {
         ownerUserId: number,
         options: KvShareHandleListOptions = {},
     ): Promise<PageResult<KvShareHandle>> {
-        const limit = clampLimit(options.limit);
+        const limit = Math.min(
+            Math.max(
+                1,
+                Math.floor(options.limit ?? KV_HANDLE_LIST_DEFAULT_LIMIT),
+            ),
+            KV_HANDLE_LIST_LIMIT_CAP,
+        );
         const after = openIdCursor(options.cursor, this.config.jwt_secret_v2);
 
         const filter = ['`owner_user_id` = ?'];

src/backend/stores/notification/NotificationStore.js

@@ -56,8 +56,7 @@ export class NotificationStore extends PuterStore {
     /**
      * A mailbox, newest first. `scope` narrows to one audience/app slice on the
      * way out of the database — `appUid: null` means the rows naming no app,
-     * which is not the same question as "any app". `excludeTypes` leaves rows
-     * of those types out.
+     * which is not the same question as "any app".
      *
      * @param {number} userId
      * @param {{
@@ -68,7 +67,6 @@ export class NotificationStore extends PuterStore {
      *         audiences: readonly string[];
      *         appUid: string | null;
      *     } | null;
-     *     excludeTypes?: readonly string[];
      * }} [opts]
      */
     async listByUserId(
@@ -78,19 +76,11 @@ export class NotificationStore extends PuterStore {
             onlyUnacknowledged = false,
             filter = undefined,
             scope = null,
-            excludeTypes = [],
         } = {},
     ) {
         const where = ['`user_id` = ?'];
         const params = [userId];
 
-        if (excludeTypes.length > 0) {
-            where.push(
-                `\`type\` NOT IN (${excludeTypes.map(() => '?').join(', ')})`,
-            );
-            params.push(...excludeTypes);
-        }
-
         if (onlyUnacknowledged || filter === 'unacknowledged') {
             where.push('`acknowledged` IS NULL');
         } else if (filter === 'unseen') {
@@ -137,7 +127,6 @@ export class NotificationStore extends PuterStore {
      * about no app, which is not the same question as "any app". `undefined` is
      * "any app": a session's own generic slice, which spans every app the
      * audience predicate already grants it rather than one named ref.
-     * `excludeTypes` leaves rows of those types out.
      *
      * @param {number} userId
      * @param {{
@@ -145,25 +134,15 @@ export class NotificationStore extends PuterStore {
      *     appUid?: string | null;
      *     after?: number | null;
      *     limit?: number;
-     *     excludeTypes?: readonly string[];
      * }} opts
      */
-    async listScoped(
-        userId,
-        { audience, appUid, after = null, limit = 50, excludeTypes = [] },
-    ) {
+    async listScoped(userId, { audience, appUid, after = null, limit = 50 }) {
         const n = Number(limit);
         const safeLimit = Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 50;
         if (safeLimit === 0) return [];
 
         const where = ['`user_id` = ?', '`audience` = ?'];
         const params = [userId, audience];
-        if (excludeTypes.length > 0) {
-            where.push(
-                `\`type\` NOT IN (${excludeTypes.map(() => '?').join(', ')})`,
-            );
-            params.push(...excludeTypes);
-        }
         if (appUid === null) {
             where.push('`app_uid` IS NULL');
         } else if (appUid !== undefined) {

src/backend/stores/permission/PermissionStore.test.ts

@@ -22,10 +22,8 @@ import { readFileSync } from 'fs';
 import { v4 as uuidv4 } from 'uuid';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { PuterServer } from '../../server.ts';
-import { PermissionUtil } from '../../services/permission/permissionUtil.ts';
 import { setupTestServer } from '../../testUtil.ts';
 import { decodeCursor } from '../../util/pagination.ts';
-import { FLAT_PERM_SCAN_CONCURRENCY } from './PermissionStore.ts';
 
 describe('PermissionStore', () => {
     let server: PuterServer;
@@ -1234,172 +1232,6 @@ describe('PermissionStore', () => {
             ).toHaveLength(2);
         });
 
-        it('takes several roots in one delete', async () => {
-            const issuer = await makeUser();
-            const holder = await makeUser();
-            const roots = ['kv-share:owner:app:a', 'kv-share-read:owner:app:b'];
-            for (const permission of [...roots, `${roots[0]}:deep`])
-                await store.upsertUserUserPerm(
-                    holder.id,
-                    issuer.id,
-                    permission,
-                    {},
-                );
-            await store.upsertUserUserPerm(
-                holder.id,
-                issuer.id,
-                'kv-share:owner:app:c',
-                {},
-            );
-
-            const removed = await store.deleteUserUserPermSubtreeForHolder(
-                holder.id,
-                issuer.id,
-                roots,
-            );
-            expect(removed.sort()).toEqual(
-                [...roots, `${roots[0]}:deep`].sort(),
-            );
-            expect(
-                await store.readLinkedUserUserPerms(holder.id, [
-                    'kv-share:owner:app:c',
-                ]),
-            ).toHaveLength(1);
-        });
-
-        it('scans flat entries a few roots at a time, once per outermost root', async () => {
-            const issuer = await makeUser();
-            const holder = await makeUser();
-            const outer = Array.from(
-                { length: 12 },
-                (_, i) => `kv-share:owner:app:r${i}`,
-            );
-            const nested = outer.map((root) => `${root}:deep`);
-            for (const root of outer) {
-                await store.upsertUserUserPerm(holder.id, issuer.id, root, {});
-                await store.setFlatUserPerm(holder.id, root, {
-                    permission: root,
-                    issuer_user_id: issuer.id,
-                });
-            }
-            // Flat only, beneath a nested root: the outer scan has to find it.
-            const orphan = `${nested[0]}:orphan`;
-            await store.setFlatUserPerm(holder.id, orphan, {
-                permission: orphan,
-                issuer_user_id: issuer.id,
-            });
-
-            const holderPrefix = PermissionUtil.join('perm', String(holder.id));
-            const dynamo = server.clients.dynamo;
-            const query = dynamo.query.bind(dynamo);
-            const scanned: string[] = [];
-            let inFlight = 0;
-            let peak = 0;
-            const spy = vi
-                .spyOn(dynamo, 'query')
-                .mockImplementation(async (...args) => {
-                    const prefix = args[6]?.beginsWith?.value;
-                    if (!prefix?.startsWith(holderPrefix))
-                        return query(...args);
-                    scanned.push(prefix);
-                    peak = Math.max(peak, ++inFlight);
-                    try {
-                        await new Promise((resolve) => setTimeout(resolve, 5));
-                        return await query(...args);
-                    } finally {
-                        inFlight--;
-                    }
-                });
-            let removed: string[];
-            try {
-                removed = await store.deleteUserUserPermSubtreeForHolder(
-                    holder.id,
-                    issuer.id,
-                    [...outer, ...nested, outer[0]],
-                );
-            } finally {
-                spy.mockRestore();
-            }
-
-            expect(peak).toBeGreaterThan(1);
-            expect(peak).toBeLessThanOrEqual(FLAT_PERM_SCAN_CONCURRENCY);
-            expect(scanned.sort()).toEqual(
-                outer
-                    .map((root) =>
-                        PermissionUtil.join('perm', String(holder.id), root),
-                    )
-                    .sort(),
-            );
-            expect(removed.sort()).toEqual([...outer].sort());
-            expect(
-                await store.getFlatUserPerms(holder.id, [...outer, orphan]),
-            ).toEqual([]);
-        });
-
-        it('deletes several exact grants of one issuer in one statement, reporting the ones it found', async () => {
-            const issuer = await makeUser();
-            const other = await makeUser();
-            const holder = await makeUser();
-            await store.upsertUserUserPerm(
-                holder.id,
-                issuer.id,
-                'kv-share:o:a:x',
-                {},
-            );
-            await store.upsertUserUserPerm(
-                holder.id,
-                issuer.id,
-                'kv-share:o:a:x:deep',
-                {},
-            );
-            await store.upsertUserUserPerm(
-                holder.id,
-                other.id,
-                'kv-share-read:o:a:x',
-                {},
-            );
-
-            const write = vi.spyOn(server.clients.db, 'write');
-            let removed: string[];
-            try {
-                removed = await store.deleteUserUserPermsByHolder(
-                    holder.id,
-                    [
-                        'kv-share:o:a:x',
-                        'kv-share-read:o:a:x',
-                        'kv-share-write:o:a:x',
-                    ],
-                    issuer.id,
-                );
-                expect(
-                    write.mock.calls.filter(([sql]) =>
-                        String(sql).startsWith('DELETE'),
-                    ),
-                ).toHaveLength(1);
-            } finally {
-                write.mockRestore();
-            }
-            expect(removed).toEqual(['kv-share:o:a:x']);
-            // Exact, not a subtree, and never another issuer's grant.
-            expect(
-                (
-                    await store.readLinkedUserUserPerms(holder.id, [
-                        'kv-share:o:a:x:deep',
-                        'kv-share-read:o:a:x',
-                    ])
-                )
-                    .map((row) => row.permission)
-                    .sort(),
-            ).toEqual(['kv-share-read:o:a:x', 'kv-share:o:a:x:deep']);
-            expect(
-                await store.deleteUserUserPermsByHolder(
-                    holder.id,
-                    [],
-                    issuer.id,
-                ),
-            ).toEqual([]);
-        });
-
         it('leaves another issuer`s subtree grant standing', async () => {
             const issuerA = await makeUser();
             const issuerB = await makeUser();

src/backend/stores/permission/PermissionStore.ts

@@ -27,7 +27,6 @@ import {
     PERMISSION_CACHE_GENERATION_TTL_SECONDS,
     PERMISSION_SCAN_CACHE_TTL_SECONDS,
 } from '../../services/permission/consts';
-import { runWithConcurrencyLimit } from '../../util/concurrency';
 import { kv } from '../../util/kvSingleton';
 import { keysetPage, openIdCursor } from '../../util/pagination';
 import { bumpGeneration } from '../../util/redisGeneration';
@@ -44,8 +43,6 @@ const ACCESS_TOKEN_PERM_INSERT_CHUNK = 100;
 
 const AUDIT_PAGE_SIZE = 50;
 const MAX_AUDIT_PAGE_SIZE = 200;
-/** Flat-entry prefix scans one subtree revoke keeps in flight. */
-export const FLAT_PERM_SCAN_CONCURRENCY = 4;
 
 /** The user-to-app grant a user's first sign-in to an app records. */
 export const APP_AUTHENTICATED_FLAG = 'flag:app-is-authenticated';
@@ -130,12 +127,6 @@ export interface UserUserAuditFilter {
     issuerUserId?: number;
     holderUserId?: number;
     permissions?: string[];
-    /**
-     * Rows under these roots are kept only where the component after the root
-     * is `ownerUuid`, for families whose grants name the owner of what they
-     * grant. Narrows the other fields; it is not a filter on its own.
-     */
-    ownedRoots?: { roots: readonly string[]; ownerUuid: string };
 }
 
 /** One entry in the flat KV view, as addressed by a delete. */
@@ -165,20 +156,6 @@ const subtreeClause = (
     ]),
 });
 
-/** `roots` less any at or beneath another of them, which that one's scan covers. */
-const outermostRoots = (roots: readonly string[]): string[] => {
-    const all = new Set(roots);
-    return [...all].filter((root) => {
-        for (
-            let at = root.indexOf(':');
-            at !== -1;
-            at = root.indexOf(':', at + 1)
-        )
-            if (all.has(root.slice(0, at))) return false;
-        return true;
-    });
-};
-
 /**
  * PermissionStore owns the _persistence_ side of permissions:
  *
@@ -504,74 +481,6 @@ export class PermissionStore extends PuterStore {
         return true;
     }
 
-    /**
-     * {@link deleteUserUserPermByHolder} for several permissions in one
-     * statement. Returns the ones that were there to delete.
-     */
-    async deleteUserUserPermsByHolder(
-        holderUserId: number,
-        permissions: readonly string[],
-        issuerUserId: number,
-    ): Promise<string[]> {
-        const found = await this.findUserUserPermsByIssuer(
-            holderUserId,
-            issuerUserId,
-            permissions,
-        );
-        if (found.length === 0) return [];
-
-        const { scope, params } = this.#issuerHolderScope(
-            holderUserId,
-            issuerUserId,
-            permissions,
-        );
-        await this.clients.db.write(
-            `DELETE FROM \`user_to_user_permissions\` WHERE ${scope}`,
-            params,
-        );
-        await this.publishCacheKeys({
-            keys: [this.#u2uCacheKey(holderUserId)],
-            broadcast: true,
-        });
-        return found;
-    }
-
-    /**
-     * Which of `permissions` this issuer granted this holder, as the primary
-     * spells them. A point lookup on the table's key.
-     */
-    async findUserUserPermsByIssuer(
-        holderUserId: number,
-        issuerUserId: number,
-        permissions: readonly string[],
-    ): Promise<string[]> {
-        if (permissions.length === 0) return [];
-        const { scope, params } = this.#issuerHolderScope(
-            holderUserId,
-            issuerUserId,
-            permissions,
-        );
-        const rows = await this.clients.db.pread(
-            `SELECT \`permission\` FROM \`user_to_user_permissions\` WHERE ${scope}`,
-            params,
-        );
-        return rows.map((row) => String(row.permission));
-    }
-
-    #issuerHolderScope(
-        holderUserId: number,
-        issuerUserId: number,
-        permissions: readonly string[],
-    ): { scope: string; params: unknown[] } {
-        const unique = [...new Set(permissions)];
-        return {
-            scope:
-                '`holder_user_id` = ? AND `issuer_user_id` = ? AND ' +
-                `\`permission\` IN (${unique.map(() => '?').join(', ')})`,
-            params: [holderUserId, issuerUserId, ...unique],
-        };
-    }
-
     /**
      * The grants an account issued, as flat-view refs. Read before the account
      * row goes: the SQL rows cascade with it, the holders' flat entries do
@@ -679,104 +588,35 @@ export class PermissionStore extends PuterStore {
     async deleteUserUserPermSubtreeForHolder(
         holderUserId: number,
         issuerUserId: number,
-        permission: string | readonly string[],
+        permission: string,
     ): Promise<string[]> {
-        const roots =
-            typeof permission === 'string' ? [permission] : [...permission];
-        if (roots.length === 0) return [];
-        const { where, params } = subtreeClause(roots);
+        const { where, params } = subtreeClause([permission]);
         const scope = '`holder_user_id` = ? AND `issuer_user_id` = ?';
         const scoped = [holderUserId, issuerUserId, ...params];
 
-        // The primary: a replica behind it misses a grant just made, whose
-        // flat entry would then outlive the revoke.
-        const removed = (
-            await this.clients.db.pread(
-                'SELECT `permission` FROM `user_to_user_permissions` ' +
-                    `WHERE ${scope} AND (${where})`,
-                scoped,
-            )
-        ).map((row) => String(row.permission));
-        if (removed.length > 0) {
-            await this.clients.db.write(
-                `DELETE FROM \`user_to_user_permissions\` WHERE ${scope} AND (${where})`,
-                scoped,
-            );
-            await this.publishCacheKeys({
-                keys: [this.#u2uCacheKey(holderUserId)],
-                broadcast: true,
-            });
-        }
+        const rows = (await this.clients.db.read(
+            'SELECT `permission` FROM `user_to_user_permissions` ' +
+                `WHERE ${scope} AND (${where})`,
+            scoped,
+        )) as Array<{ permission: string }>;
+        if (rows.length === 0) return [];
 
-        // The whole flat subtree, not only what SQL returned: an entry can
-        // outlive its row. An entry another issuer's row still backs is kept.
-        const candidates = [
-            ...new Set([
-                ...removed,
-                ...(await this.#flatPermsUnder(holderUserId, roots)),
-            ]),
-        ];
-        if (candidates.length === 0) return removed;
-        const remaining = new Set(
-            (
-                await this.readLinkedUserUserPermsFromPrimary(
-                    holderUserId,
-                    candidates,
-                )
-            ).map((row) => row.permission),
+        await this.clients.db.write(
+            `DELETE FROM \`user_to_user_permissions\` WHERE ${scope} AND (${where})`,
+            scoped,
         );
+
+        const removed = rows.map((row) => String(row.permission));
         await this.delFlatUserPerms(
-            candidates
-                .filter((perm) => !remaining.has(perm))
-                .map((perm) => ({ holderUserId, permission: perm })),
+            removed.map((perm) => ({ holderUserId, permission: perm })),
         );
+        await this.publishCacheKeys({
+            keys: [this.#u2uCacheKey(holderUserId)],
+            broadcast: true,
+        });
         return removed;
     }
 
-    /**
-     * The flat entries a holder has at or beneath any of `roots`, found by key
-     * prefix, so an entry with no SQL row behind it is found too.
-     */
-    async #flatPermsUnder(
-        holderUserId: number,
-        roots: readonly string[],
-    ): Promise<string[]> {
-        const holderKey = PermissionUtil.join(
-            PERM_KEY_PREFIX,
-            String(holderUserId),
-        );
-        const escapedSeparator =
-            PermissionUtil.escape_permission_component(':');
-        const found = await runWithConcurrencyLimit(
-            outermostRoots(roots),
-            FLAT_PERM_SCAN_CONCURRENCY,
-            async (root) => {
-                const base = PermissionUtil.join(
-                    PERM_KEY_PREFIX,
-                    String(holderUserId),
-                    root,
-                );
-                const { res } = await this.stores.kv.list({
-                    as: 'keys',
-                    keyPrefix: base,
-                });
-                // The prefix also matches siblings that merely start the same.
-                return (res as string[])
-                    .filter(
-                        (key) =>
-                            key === base ||
-                            key.startsWith(`${base}${escapedSeparator}`),
-                    )
-                    .map((key) =>
-                        PermissionUtil.unescape_permission_component(
-                            key.slice(holderKey.length + 1),
-                        ),
-                    );
-            },
-        );
-        return found.flat();
-    }
-
     async auditUserUserPerm(
         entry: AuditEntry & {
             holder_user_id: number;
@@ -879,16 +719,6 @@ export class PermissionStore extends PuterStore {
         if (clauses.length === 0) {
             throw new Error('listUserUserAudit requires a filter');
         }
-        const owned = filter.ownedRoots;
-        for (const root of owned?.roots ?? []) {
-            clauses.push(
-                "NOT (`permission` LIKE ? ESCAPE '!' AND `permission` NOT LIKE ? ESCAPE '!')",
-            );
-            params.push(
-                `${escapeLike(root)}:%`,
-                `${escapeLike(`${root}:${owned?.ownerUuid}`)}:%`,
-            );
-        }
         return { sql: clauses.join(' AND '), params };
     }
 

src/backend/stores/systemKv/SystemKVStore.test.ts

@@ -3312,70 +3312,14 @@ describe('SystemKVStore', () => {
         it('bills the probe as a read', async () => {
             // The probe is a real round trip; metering runs off the usage the
             // store reports, so swallowing it under-bills the caller.
-            const { usage } = await target.update(
-                { key: 'metered', pathAndValueMap: { a: 1 } },
+            const { usage } = await target.set(
+                { key: 'metered', value: 'v' },
                 crossOpts,
             );
             expect(usage.read).toBeGreaterThan(0);
             expect(usage.write).toBeGreaterThan(0);
         });
 
-        it('checks set and del in the write itself, with no read before it', async () => {
-            const get = vi.spyOn(server.clients.dynamo, 'get');
-            try {
-                const written = await target.set(
-                    { key: 'one-trip', value: 'v' },
-                    crossOpts,
-                );
-                expect(written.usage.read).toBe(0);
-                expect(written.usage.write).toBeGreaterThan(0);
-                const deleted = await target.del(
-                    { key: 'one-trip' },
-                    crossOpts,
-                );
-                expect(deleted.usage.read).toBe(0);
-                expect(get).not.toHaveBeenCalled();
-            } finally {
-                get.mockRestore();
-            }
-        });
-
-        it('refuses set and del on a private entry, leaving it as it was', async () => {
-            const own = { actor, appUuid: 'app-other' };
-            await target.set(
-                { key: 'kept-secret', value: 's', disableSharing: true },
-                own,
-            );
-            await expect(
-                target.set({ key: 'kept-secret', value: 'x' }, crossOpts),
-            ).rejects.toMatchObject({ statusCode: 403 });
-            await expect(
-                target.del({ key: 'kept-secret' }, crossOpts),
-            ).rejects.toMatchObject({ statusCode: 403 });
-            expect((await target.get({ key: 'kept-secret' }, own)).res).toBe(
-                's',
-            );
-        });
-
-        it('writes over a private entry whose expiry has passed', async () => {
-            const own = { actor, appUuid: 'app-other' };
-            await target.set(
-                {
-                    key: 'lapsed-secret',
-                    value: 's',
-                    disableSharing: true,
-                    expireAt: Math.floor(Date.now() / 1000) - 10,
-                },
-                own,
-            );
-            await expect(
-                target.set({ key: 'lapsed-secret', value: 'x' }, crossOpts),
-            ).resolves.toMatchObject({ res: true });
-            expect((await target.get({ key: 'lapsed-secret' }, own)).res).toBe(
-                'x',
-            );
-        });
-
         it('still refuses a private entry through the batch probe', async () => {
             // Into the *target* namespace: a plain user actor may address any of
             // its own app namespaces via `appUuid`, which is how the owning app's
@@ -3519,188 +3463,6 @@ describe('SystemKVStore', () => {
         });
     });
 
-    // -- Another user's namespace -------------------------------------
-    //
-    // Reached only through `namespaceUser`, which the KV driver sets after a
-    // share handle's check has passed.
-    describe('another user`s namespace', () => {
-        let owner: Actor;
-        let holderOpts: {
-            actor: Actor;
-            namespaceUser: { uuid: string; id: number };
-            namespaceAppUuid: string;
-        };
-        beforeEach(() => {
-            owner = {
-                user: {
-                    id: 7001,
-                    uuid: `owner-${Math.random().toString(36).slice(2)}`,
-                },
-                effectiveApp: null,
-            };
-            holderOpts = {
-                actor,
-                namespaceUser: {
-                    uuid: owner.user.uuid!,
-                    id: owner.user.id!,
-                },
-                namespaceAppUuid: KV_GLOBAL_APP_KEY,
-            };
-        });
-
-        it('reads and writes the owner`s data, not the caller`s', async () => {
-            await target.set(
-                { key: 'shared', value: 'mine' },
-                { actor: owner },
-            );
-            expect((await target.get({ key: 'shared' }, holderOpts)).res).toBe(
-                'mine',
-            );
-            await target.set({ key: 'shared', value: 'theirs' }, holderOpts);
-            expect(
-                (await target.get({ key: 'shared' }, { actor: owner })).res,
-            ).toBe('theirs');
-            expect((await target.get({ key: 'shared' }, opts)).res).toBeNull();
-        });
-
-        it('hides private entries from get, list and total, and refuses writes to them', async () => {
-            await target.set({ key: 'p:open', value: 1 }, { actor: owner });
-            await target.set(
-                { key: 'p:hidden', value: 2, disableSharing: true },
-                { actor: owner },
-            );
-            expect(
-                (await target.get({ key: 'p:hidden' }, holderOpts)).res,
-            ).toBeNull();
-            const listed = await target.list(
-                { as: 'keys', limit: 10, includeTotal: true, pattern: 'p:*' },
-                holderOpts,
-            );
-            expect(listed.res).toEqual({ items: ['p:open'], total: 1 });
-            await expect(
-                target.incr(
-                    { key: 'p:hidden', pathAndAmountMap: { '': 1 } },
-                    holderOpts,
-                ),
-            ).rejects.toMatchObject({ statusCode: 403 });
-            await expect(
-                target.set({ key: 'p:hidden', value: 3 }, holderOpts),
-            ).rejects.toMatchObject({ statusCode: 403 });
-        });
-    });
-
-    describe('onlyIfAbsent', () => {
-        it('writes once, then leaves a live entry alone', async () => {
-            const first = await target.set(
-                { key: 'claim', value: 'a', onlyIfAbsent: true },
-                opts,
-            );
-            const second = await target.set(
-                { key: 'claim', value: 'b', onlyIfAbsent: true },
-                opts,
-            );
-            expect(first.res).toBe(true);
-            expect(second.res).toBe(false);
-            expect(second.usage.write).toBeGreaterThan(0);
-            expect((await target.get({ key: 'claim' }, opts)).res).toBe('a');
-        });
-
-        it('treats an expired row that has not been swept as absent', async () => {
-            await target.set(
-                {
-                    key: 'lapsed',
-                    value: 'old',
-                    expireAt: Math.floor(Date.now() / 1000) - 10,
-                },
-                opts,
-            );
-            const res = await target.set(
-                { key: 'lapsed', value: 'new', onlyIfAbsent: true },
-                opts,
-            );
-            expect(res.res).toBe(true);
-            expect((await target.get({ key: 'lapsed' }, opts)).res).toBe('new');
-        });
-
-        it('announces only the write that landed', async () => {
-            // A user row id is what a mutation event keys on.
-            const withId = {
-                actor: { ...actor, user: { ...actor.user, id: 9 } },
-            };
-            const emit = vi.spyOn(server.clients.event, 'emit');
-            try {
-                await target.set(
-                    { key: 'once', value: 1, onlyIfAbsent: true },
-                    withId,
-                );
-                await target.set(
-                    { key: 'once', value: 2, onlyIfAbsent: true },
-                    withId,
-                );
-                const mutations = emit.mock.calls.filter(
-                    ([key]) => key === 'kv.mutated',
-                );
-                expect(mutations).toHaveLength(1);
-            } finally {
-                emit.mockRestore();
-            }
-        });
-
-        it('answers false for a live private entry in a foreign namespace', async () => {
-            const own = { actor, appUuid: 'app-other' };
-            await target.set(
-                { key: 'private-claim', value: 's', disableSharing: true },
-                own,
-            );
-            const res = await target.set(
-                { key: 'private-claim', value: 'x', onlyIfAbsent: true },
-                { actor, namespaceAppUuid: 'app-other' },
-            );
-            expect(res.res).toBe(false);
-            expect((await target.get({ key: 'private-claim' }, own)).res).toBe(
-                's',
-            );
-        });
-    });
-
-    describe('list within a key prefix', () => {
-        beforeEach(async () => {
-            for (const key of [' room:a', ' room:b', 'room:c', ' roomy'])
-                await target.set({ key, value: key }, opts);
-        });
-
-        it('lists only under the prefix, reading the pattern below it', async () => {
-            const all = await target.list(
-                { as: 'keys', keyPrefix: ' room:' },
-                opts,
-            );
-            expect(all.res).toEqual([' room:a', ' room:b']);
-            const narrowed = await target.list(
-                { as: 'keys', keyPrefix: ' room:', pattern: 'b*' },
-                opts,
-            );
-            expect(narrowed.res).toEqual([' room:b']);
-        });
-
-        it('keeps a prefix that starts with whitespace, where a pattern is trimmed', async () => {
-            // Trimmed as a pattern, ` room:` would widen to `room:`.
-            const res = await target.list(
-                {
-                    as: 'keys',
-                    keyPrefix: ' room:',
-                    pattern: '  ',
-                    limit: 10,
-                    includeTotal: true,
-                },
-                opts,
-            );
-            expect(res.res).toEqual({
-                items: [' room:a', ' room:b'],
-                total: 2,
-            });
-        });
-    });
-
     describe('take', () => {
         it('returns the value to exactly one caller, null after', async () => {
             await target.set({ key: 'claim-me', value: { by: 'me' } }, opts);
@@ -4194,85 +3956,6 @@ describe('SystemKVStore', () => {
             expect(listed.res).not.toContain('legacyStringPast');
         });
 
-        it('onlyIfAbsent writes over a legacy expired string-ttl row', async () => {
-            const namespace = namespaceOf(actor);
-            const past = String(Math.floor(Date.now() / 1000) - 3600);
-            await server.clients.dynamo.put(PUTER_KV_STORE_TABLE_NAME, {
-                namespace,
-                key: 'legacyStringClaim',
-                value: 'old',
-                ttl: past,
-            });
-            const res = await target.set(
-                { key: 'legacyStringClaim', value: 'new', onlyIfAbsent: true },
-                opts,
-            );
-            expect(res.res).toBe(true);
-            expect(
-                (await target.get({ key: 'legacyStringClaim' }, opts)).res,
-            ).toBe('new');
-        });
-
-        it('onlyIfAbsent still answers false over a legacy future string-ttl row', async () => {
-            const namespace = namespaceOf(actor);
-            const future = String(Math.floor(Date.now() / 1000) + 3600);
-            await server.clients.dynamo.put(PUTER_KV_STORE_TABLE_NAME, {
-                namespace,
-                key: 'legacyStringHeld',
-                value: 'old',
-                ttl: future,
-            });
-            const res = await target.set(
-                { key: 'legacyStringHeld', value: 'new', onlyIfAbsent: true },
-                opts,
-            );
-            expect(res.res).toBe(false);
-            expect(
-                (await target.get({ key: 'legacyStringHeld' }, opts)).res,
-            ).toBe('old');
-        });
-
-        it('a foreign set and del go through a private entry whose legacy string ttl has passed', async () => {
-            const namespace = kvNamespace(actor.user.uuid!, 'app-other');
-            const foreign = { actor, namespaceAppUuid: 'app-other' };
-            const past = String(Math.floor(Date.now() / 1000) - 3600);
-            for (const key of ['legacyPrivateSet', 'legacyPrivateDel'])
-                await server.clients.dynamo.put(PUTER_KV_STORE_TABLE_NAME, {
-                    namespace,
-                    key,
-                    value: 'hidden',
-                    ttl: past,
-                    noShare: true,
-                });
-
-            await expect(
-                target.set({ key: 'legacyPrivateSet', value: 'mine' }, foreign),
-            ).resolves.toMatchObject({ res: true });
-            expect(
-                (await target.get({ key: 'legacyPrivateSet' }, foreign)).res,
-            ).toBe('mine');
-            await expect(
-                target.del({ key: 'legacyPrivateDel' }, foreign),
-            ).resolves.toMatchObject({ res: true });
-        });
-
-        it('a foreign set still refuses a private entry whose legacy string ttl is in the future', async () => {
-            const namespace = kvNamespace(actor.user.uuid!, 'app-other');
-            await server.clients.dynamo.put(PUTER_KV_STORE_TABLE_NAME, {
-                namespace,
-                key: 'legacyPrivateLive',
-                value: 'hidden',
-                ttl: String(Math.floor(Date.now() / 1000) + 3600),
-                noShare: true,
-            });
-            await expect(
-                target.set(
-                    { key: 'legacyPrivateLive', value: 'mine' },
-                    { actor, namespaceAppUuid: 'app-other' },
-                ),
-            ).rejects.toMatchObject({ statusCode: 403 });
-        });
-
         it('a legacy row with a non-numeric string ttl is readable by get and list', async () => {
             const namespace = namespaceOf(actor);
             await server.clients.dynamo.put(PUTER_KV_STORE_TABLE_NAME, {

src/backend/stores/systemKv/SystemKVStore.ts

@@ -24,7 +24,6 @@ import {
     isSystemActor,
     SYSTEM_ACTOR,
     SYSTEM_ACTOR_UUID,
-    viaWorkerOf,
 } from '../../core/actor';
 import { HttpError } from '../../core/http';
 import {
@@ -130,12 +129,6 @@ export interface KVOpts {
      * only after its cross-app permission check has passed.
      */
     namespaceAppUuid?: string;
-    /**
-     * Namespace override that wins over the actor's own user — how a share
-     * holder addresses the owner's data. Set only by the KV driver, after its
-     * handle check has passed.
-     */
-    namespaceUser?: { uuid: string; id: number };
     /**
      * Files system data under its own partition of the system namespace, so a
      * high-volume key family doesn't share one partition key with the rest of
@@ -156,8 +149,7 @@ export const KV_GLOBAL_APP_KEY = 'os-global';
 const SYSTEM_NAMESPACE = `v1:${SYSTEM_ACTOR_UUID}:${KV_GLOBAL_APP_KEY}`;
 // The extra segment keeps a partition from parsing as a user's namespace.
 const SYSTEM_PARTITION_PREFIX = `${SYSTEM_NAMESPACE}:`;
-/** Longest key the store accepts, in UTF-8 bytes. */
-export const KV_MAX_KEY_BYTES = 1024;
+const MAX_KEY_BYTES = 1024;
 
 /**
  * Whether a write was refused because the condition it carried no longer held.
@@ -186,8 +178,6 @@ const PATH_CLEANER_REGEX = /[^A-Za-z0-9_]/g;
 // is bounded; cursors are the recommended way to page.
 const MAX_LIST_OFFSET = 5000;
 const MAX_FILL_PAGES = 10;
-/** Most items one query reads while a foreign listing skips hidden entries. */
-const MAX_HIDDEN_SKIP_READ = 1000;
 // Cache keys carried by one invalidation broadcast. A peer applies them in a
 // single pass either way; the cap only keeps an individual message a sane size.
 const KV_CACHE_BROADCAST_CHUNK = 500;
@@ -249,31 +239,6 @@ const expiredRowFilter = (now: number) => {
     return { ...live, expression: `NOT (${live.expression})` };
 };
 
-/** No item, or an expired one: where an `onlyIfAbsent` write may land. */
-const absentRowCondition = (now: number) => {
-    const expired = expiredRowFilter(now);
-    return {
-        expression: `attribute_not_exists(#key) OR (${expired.expression})`,
-        names: { ...expired.names, '#key': 'key' },
-        values: expired.values,
-    };
-};
-
-/** No live private entry: where a write into a foreign namespace may land. */
-const notPrivateCondition = (now: number) => {
-    const expired = expiredRowFilter(now);
-    return {
-        expression: `attribute_not_exists(#privAttr) OR (${expired.expression})`,
-        names: { ...expired.names, '#privAttr': KV_PRIVATE_ATTR },
-        values: expired.values,
-    };
-};
-
-const privateEntryError = (): HttpError =>
-    new HttpError(403, 'kv: this entry is private to the app that wrote it', {
-        legacyCode: 'forbidden',
-    });
-
 /**
  * A timestamp at or before now is stored as `floor(now)` rather than as-is, so
  * it still sweeps (never `0`, which reads as no expiry).
@@ -354,14 +319,13 @@ const isNestingTooDeep = (err: unknown): boolean =>
 const MAX_LIVE_WRITE_ATTEMPTS = 3;
 
 /**
- * Expired entries, plus private ones for a caller in a foreign namespace.
- * Filtered in the query rather than afterwards so `includeTotal`'s COUNT
- * excludes them too — a total counting rows the caller can't see would leak
- * what the flag hides.
+ * Expired entries, plus private ones for a cross-app caller. Filtered in the
+ * query rather than afterwards so `includeTotal`'s COUNT excludes them too — a
+ * total counting rows the caller can't see would leak what the flag hides.
  */
-const listFilter = (now: number, foreign: boolean) => {
+const listFilter = (now: number, crossApp: boolean) => {
     const live = liveRowFilter(now);
-    if (!foreign) return live;
+    if (!crossApp) return live;
     return {
         expression: `(${live.expression}) AND attribute_not_exists(#privAttr)`,
         names: { ...live.names, '#privAttr': KV_PRIVATE_ATTR },
@@ -397,12 +361,7 @@ const addUsage = (a: KVUsage, b: KVUsage): KVUsage => ({
 
 const ensureActor = (opts?: KVOpts): Actor => opts?.actor ?? SYSTEM_ACTOR;
 
-/**
- * Another app's namespace, or another user's: where private entries read as
- * absent and refuse writes.
- */
-const isForeignNamespace = (opts?: KVOpts): boolean =>
-    Boolean(opts?.namespaceAppUuid || opts?.namespaceUser);
+const isCrossApp = (opts?: KVOpts): boolean => Boolean(opts?.namespaceAppUuid);
 
 // `effectiveApp`, not `app`, so the namespace agrees with the gate the driver
 // applied: both read an access-token actor as the app that issued it, rather
@@ -419,7 +378,7 @@ const getNamespace = (actor: Actor, opts?: KVOpts): string => {
         actor.effectiveApp?.uid ??
         opts?.appUuid ??
         KV_GLOBAL_APP_KEY;
-    return kvNamespace(opts?.namespaceUser?.uuid ?? actor.user.uuid!, appUuid);
+    return kvNamespace(actor.user.uuid!, appUuid);
 };
 
 /** The namespace one user's data for one app lives in. */
@@ -446,10 +405,10 @@ const assertKey = (key: string): void => {
         throw new HttpError(400, 'kv: key is empty', {
             legacyCode: 'bad_request',
         });
-    if (Buffer.byteLength(key, 'utf8') > KV_MAX_KEY_BYTES) {
+    if (Buffer.byteLength(key, 'utf8') > MAX_KEY_BYTES) {
         throw new HttpError(
             400,
-            `kv: key exceeds ${KV_MAX_KEY_BYTES} byte limit`,
+            `kv: key exceeds ${MAX_KEY_BYTES} byte limit`,
             { legacyCode: 'bad_request' },
         );
     }
@@ -1454,7 +1413,7 @@ export class SystemKVStore extends PuterStore {
      * the change.
      */
     async #committed(
-        opts: KVOpts | undefined,
+        actor: Actor,
         namespace: string,
         keys: string[],
         op: KvMutation,
@@ -1462,7 +1421,7 @@ export class SystemKVStore extends PuterStore {
         noShareKeys?: string[],
     ): Promise<void> {
         await this.#invalidate(namespace, keys);
-        this.#emitMutation(opts, namespace, keys, op, values, noShareKeys);
+        this.#emitMutation(actor, namespace, keys, op, values, noShareKeys);
     }
 
     /**
@@ -1470,32 +1429,24 @@ export class SystemKVStore extends PuterStore {
      * large namespace doesn't turn into an unbounded event.
      */
     #emitMutation(
-        opts: KVOpts | undefined,
+        actor: Actor,
         namespace: string,
         keys: string[],
         op: KvMutation,
         values?: unknown[],
         noShareKeys?: string[],
     ): void {
-        const actor = ensureActor(opts);
         // Internal system data has no subscribable subject, and it is written
         // often enough that the emit itself would be the cost.
         if (isSystemActor(actor)) return;
-        // Dispatch keys on the namespace's owner, who is not the writer when a
-        // share holder wrote it.
-        const userId = opts?.namespaceUser?.id ?? actor.user?.id;
+        const userId = actor.user?.id;
         if (typeof userId !== 'number') return;
-        const actingUserId = actor.user?.id;
-        const writer = {
-            ...(typeof actingUserId === 'number' ? { actingUserId } : {}),
-            ...(viaWorkerOf(actor) ? { viaWorker: true as const } : {}),
-        };
 
         try {
             if (op === 'flush') {
                 this.clients.event.emit(
                     'kv.flushed',
-                    { namespace, userId, ...writer },
+                    { namespace, userId },
                     {},
                 );
                 return;
@@ -1520,7 +1471,6 @@ export class SystemKVStore extends PuterStore {
                     ...(actor.handlerDepth
                         ? { handlerDepth: actor.handlerDepth }
                         : {}),
-                    ...writer,
                 },
                 {},
             );
@@ -1763,17 +1713,16 @@ export class SystemKVStore extends PuterStore {
     // -- Public API ---------------------------------------------------
 
     /**
-     * Refuse a path write into a foreign namespace against a private entry. Not
-     * atomic with the write that follows, so one in-flight write can still land
-     * on an entry the owner flags in between; `set` and `del` carry the check
-     * in their own write instead.
+     * Refuse a cross-app mutation against a private entry. Not atomic with the
+     * write that follows, so one in-flight write can still land on an entry the
+     * owner flags in between.
      */
     async #assertNotPrivate(
         namespace: string,
         key: string,
         opts?: KVOpts,
     ): Promise<KVUsage> {
-        if (!isForeignNamespace(opts)) return emptyUsage();
+        if (!isCrossApp(opts)) return emptyUsage();
         let response = await this.clients.dynamo.get(this.tableName, {
             namespace,
             key,
@@ -1804,7 +1753,11 @@ export class SystemKVStore extends PuterStore {
             response.Item?.[KV_PRIVATE_ATTR] &&
             !isExpiredTtl(response.Item.ttl, Date.now() / 1000)
         ) {
-            throw privateEntryError();
+            throw new HttpError(
+                403,
+                'kv: this entry is private to the app that wrote it',
+                { legacyCode: 'forbidden' },
+            );
         }
         // Returned rather than swallowed: the probe is a real read, and a caller
         // that did not pay for it is under-billed for the operation.
@@ -1820,7 +1773,7 @@ export class SystemKVStore extends PuterStore {
         keys: string[],
         opts?: KVOpts,
     ): Promise<KVUsage> {
-        if (!isForeignNamespace(opts) || keys.length === 0) return emptyUsage();
+        if (!isCrossApp(opts) || keys.length === 0) return emptyUsage();
         const { entries, usage } = await this.getBatches(namespace, keys);
         const now = Date.now() / 1000;
 
@@ -1858,7 +1811,13 @@ export class SystemKVStore extends PuterStore {
         const isPrivate = confirmedEntries.some(
             (entry) => entry?.noShare && !isExpiredTtl(entry.ttl, now),
         );
-        if (isPrivate) throw privateEntryError();
+        if (isPrivate) {
+            throw new HttpError(
+                403,
+                'kv: this entry is private to the app that wrote it',
+                { legacyCode: 'forbidden' },
+            );
+        }
         return addUsage(usage, recheckUsage);
     }
 
@@ -1989,34 +1948,6 @@ export class SystemKVStore extends PuterStore {
         }
     }
 
-    /**
-     * A write whose condition may refuse it, retried once after settling a row
-     * the condition reads as live but reads treat as expired (a legacy text or
-     * boolean `ttl`). `response` is `null` when the condition still refuses.
-     */
-    async #writeUnlessRefused<R>(
-        namespace: string,
-        key: string,
-        write: () => Promise<R>,
-    ): Promise<{ response: R | null; usage: KVUsage }> {
-        try {
-            return { response: await write(), usage: emptyUsage() };
-        } catch (e) {
-            if (!isConditionRefused(e)) throw e;
-        }
-        // A refused conditional write still consumes capacity.
-        const usage = addUsage(
-            writeUsage(1),
-            await this.#dropIfExpired(namespace, key),
-        );
-        try {
-            return { response: await write(), usage };
-        } catch (e) {
-            if (!isConditionRefused(e)) throw e;
-            return { response: null, usage: addUsage(usage, writeUsage(1)) };
-        }
-    }
-
     async get(
         {
             key,
@@ -2026,7 +1957,7 @@ export class SystemKVStore extends PuterStore {
     ): Promise<KVResult<unknown | null | (unknown | null)[]>> {
         const actor = ensureActor(opts);
         const namespace = getNamespace(actor, opts);
-        const foreign = isForeignNamespace(opts);
+        const crossApp = isCrossApp(opts);
         const multi = Array.isArray(key);
         const keys = multi ? key : [key];
 
@@ -2097,24 +2028,19 @@ export class SystemKVStore extends PuterStore {
             if (!entry) return null;
             if (isExpiredTtl(entry.ttl, now)) return null;
             // Absent rather than refused: the flag must not confirm the key.
-            if (foreign && entry.noShare) return null;
+            if (crossApp && entry.noShare) return null;
             return entry.value ?? null;
         });
 
         return { res: multi ? values : values[0], usage };
     }
 
-    /**
-     * `res` is `false` only for an `onlyIfAbsent` write that found a live
-     * entry, which is left as it was.
-     */
     async set(
         {
             key,
             value,
             expireAt,
             disableSharing,
-            onlyIfAbsent,
         }: {
             key: string;
             value: unknown;
@@ -2125,11 +2051,6 @@ export class SystemKVStore extends PuterStore {
              * on a later write is how the owner re-shares the entry.
              */
             disableSharing?: boolean;
-            /**
-             * Write only when no live entry holds the key; an expired one that
-             * hasn't been swept counts as absent.
-             */
-            onlyIfAbsent?: boolean;
         },
         opts?: KVOpts,
     ): Promise<KVResult<boolean>> {
@@ -2138,51 +2059,23 @@ export class SystemKVStore extends PuterStore {
         const ttl = coerceExpiry(expireAt, 'expireAt');
         const actor = ensureActor(opts);
         const namespace = getNamespace(actor, opts);
-        // The put carries the check rather than a read before it: any live
-        // entry refuses `onlyIfAbsent`, which covers a private one too.
-        const now = Date.now() / 1000;
-        const condition = onlyIfAbsent
-            ? absentRowCondition(now)
-            : isForeignNamespace(opts)
-              ? notPrivateCondition(now)
-              : undefined;
+        const probeUsage = await this.#assertNotPrivate(namespace, key, opts);
 
-        const put = () =>
-            this.clients.dynamo.put(
-                this.tableName,
-                {
-                    namespace,
-                    key,
-                    value,
-                    ...(ttl ? { ttl: storedExpiry(ttl) } : {}),
-                    ...(disableSharing ? { [KV_PRIVATE_ATTR]: true } : {}),
-                },
-                condition ? { condition } : undefined,
-            );
-        let response: Awaited<ReturnType<typeof put>> | null;
-        let settleUsage = emptyUsage();
+        let response: Awaited<ReturnType<typeof this.clients.dynamo.put>>;
         try {
-            if (condition) {
-                const outcome = await this.#writeUnlessRefused(
-                    namespace,
-                    key,
-                    put,
-                );
-                response = outcome.response;
-                settleUsage = outcome.usage;
-            } else {
-                response = await put();
-            }
+            response = await this.clients.dynamo.put(this.tableName, {
+                namespace,
+                key,
+                value,
+                ...(ttl ? { ttl: storedExpiry(ttl) } : {}),
+                ...(disableSharing ? { [KV_PRIVATE_ATTR]: true } : {}),
+            });
         } catch (e) {
             if (isNestingTooDeep(e)) throw tooDeeplyNestedError(undefined, e);
             throw e;
         }
-        if (response === null) {
-            if (onlyIfAbsent) return { res: false, usage: settleUsage };
-            throw privateEntryError();
-        }
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'set',
@@ -2193,11 +2086,10 @@ export class SystemKVStore extends PuterStore {
         return {
             res: true,
             usage: addUsage(
-                settleUsage,
+                probeUsage,
                 writeUsage(
                     response.ConsumedCapacity?.CapacityUnits as
-                        | number
-                        | undefined,
+                        number | undefined,
                 ),
             ),
         };
@@ -2271,7 +2163,7 @@ export class SystemKVStore extends PuterStore {
             throw e;
         }
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [...byKey.keys()],
             'set',
@@ -2297,28 +2189,17 @@ export class SystemKVStore extends PuterStore {
         assertKey(key);
         const actor = ensureActor(opts);
         const namespace = getNamespace(actor, opts);
-        // The delete carries the private-entry check rather than a read first.
-        const condition = isForeignNamespace(opts)
-            ? notPrivateCondition(Date.now() / 1000)
-            : undefined;
+        const probeUsage = await this.#assertNotPrivate(namespace, key, opts);
 
         // The old item is only worth reading back for the private-key check,
         // which a system write never needs an event for anyway.
-        const del = () =>
-            this.clients.dynamo.del(
-                this.tableName,
-                { namespace, key },
-                {
-                    returnOld: !isSystemActor(actor),
-                    ...(condition ? { condition } : {}),
-                },
-            );
-        const { response, usage: settleUsage } = condition
-            ? await this.#writeUnlessRefused(namespace, key, del)
-            : { response: await del(), usage: emptyUsage() };
-        if (response === null) throw privateEntryError();
+        const response = await this.clients.dynamo.del(
+            this.tableName,
+            { namespace, key },
+            { returnOld: !isSystemActor(actor) },
+        );
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'del',
@@ -2328,11 +2209,10 @@ export class SystemKVStore extends PuterStore {
         return {
             res: true,
             usage: addUsage(
-                settleUsage,
+                probeUsage,
                 writeUsage(
                     (response.ConsumedCapacity?.CapacityUnits as
-                        | number
-                        | undefined) ?? 1,
+                        number | undefined) ?? 1,
                 ),
             ),
         };
@@ -2358,7 +2238,7 @@ export class SystemKVStore extends PuterStore {
             { returnOld: true },
         );
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'del',
@@ -2420,15 +2300,15 @@ export class SystemKVStore extends PuterStore {
             })),
         );
         await this.#committed(
-            opts,
+            actor,
             namespace,
             uniqueKeys,
             'del',
             uniqueKeys.map((): unknown => null),
             // A batch delete reports no prior state, so a same-app batch is
-            // marked private wholesale; a foreign caller was already refused
-            // any private key.
-            isForeignNamespace(opts) ? undefined : uniqueKeys,
+            // marked private wholesale; a cross-app caller was already
+            // refused any private key.
+            isCrossApp(opts) ? undefined : uniqueKeys,
         );
         const units =
             response.ConsumedCapacity?.reduce(
@@ -2452,7 +2332,6 @@ export class SystemKVStore extends PuterStore {
             includeTotal,
             fetchUntilFull,
             reverse,
-            keyPrefix,
         }: {
             as?: 'keys' | 'values' | 'entries';
             limit?: number;
@@ -2462,12 +2341,6 @@ export class SystemKVStore extends PuterStore {
             includeTotal?: boolean;
             fetchUntilFull?: boolean;
             reverse?: boolean;
-            /**
-             * Confines the listing to keys under this prefix, with `pattern`
-             * read below it. Taken as-is, where `pattern` is trimmed, so no
-             * pattern can widen it.
-             */
-            keyPrefix?: string;
         },
         opts?: KVOpts,
     ): Promise<
@@ -2535,7 +2408,7 @@ export class SystemKVStore extends PuterStore {
             }
         }
         const effectiveReverse = reverse ?? cursorReverse;
-        const scanPrefix = `${keyPrefix ?? ''}${normalizePattern(pattern) ?? ''}`;
+        const normalizedPattern = normalizePattern(pattern);
 
         if (pageKey !== undefined && normalizedOffset !== undefined) {
             throw new HttpError(
@@ -2584,15 +2457,15 @@ export class SystemKVStore extends PuterStore {
                 false,
                 {
                     scanIndexForward: !effectiveReverse,
-                    ...(scanPrefix
+                    ...(normalizedPattern
                         ? {
                               beginsWith: {
                                   key: 'key',
-                                  value: scanPrefix,
+                                  value: normalizedPattern,
                               },
                           }
                         : {}),
-                    filter: listFilter(now, isForeignNamespace(opts)),
+                    filter: listFilter(now, isCrossApp(opts)),
                     ...(select ? { select } : {}),
                 },
             );
@@ -2628,9 +2501,6 @@ export class SystemKVStore extends PuterStore {
             }
         }
 
-        // Another namespace's page goes on past entries it hides, reading
-        // further each time, so its cursor can sit on an entry it shows.
-        const foreign = isForeignNamespace(opts);
         const collected: Array<Record<string, unknown>> = [];
         let nextKey = startKey;
         if (!exhausted) {
@@ -2639,13 +2509,7 @@ export class SystemKVStore extends PuterStore {
                 const want = normalizedLimit
                     ? normalizedLimit - collected.length
                     : 0;
-                const skipping = foreign && pages > 0 && collected.length === 0;
-                const response = await runQuery(
-                    skipping
-                        ? Math.min(want * 2 ** pages, MAX_HIDDEN_SKIP_READ)
-                        : want,
-                    nextKey,
-                );
+                const response = await runQuery(want, nextKey);
                 collected.push(
                     ...((response.Items ?? []) as Array<
                         Record<string, unknown>
@@ -2659,7 +2523,7 @@ export class SystemKVStore extends PuterStore {
                     // result is complete rather than capped at one response.
                     if (!nextKey) break;
                 } else if (
-                    (!fetchUntilFull && !(foreign && collected.length === 0)) ||
+                    !fetchUntilFull ||
                     collected.length >= normalizedLimit ||
                     !nextKey ||
                     pages >= MAX_FILL_PAGES
@@ -2669,16 +2533,6 @@ export class SystemKVStore extends PuterStore {
             } while (true);
         }
 
-        // The scan may have stopped on a private entry, so a foreign cursor
-        // resumes after the last entry kept, which a read-ahead can overshoot.
-        let resumeKey = nextKey;
-        if (foreign && normalizedLimit !== undefined) {
-            const overshot = collected.splice(normalizedLimit).length > 0;
-            const last = collected[collected.length - 1];
-            if (last && (nextKey || overshot))
-                resumeKey = { namespace, key: last.key };
-        }
-
         const entries = collected
             .filter((e) => e && !isExpiredTtl(e.ttl, now))
             .map((e) => ({ key: e.key as string, value: e.value }));
@@ -2706,9 +2560,9 @@ export class SystemKVStore extends PuterStore {
         }
 
         const nextCursor = encodeCursor(
-            resumeKey && effectiveReverse
-                ? { reverse: true, key: resumeKey }
-                : resumeKey,
+            nextKey && effectiveReverse
+                ? { reverse: true, key: nextKey }
+                : nextKey,
         );
         return {
             res: {
@@ -2776,7 +2630,7 @@ export class SystemKVStore extends PuterStore {
                     Record<string, unknown> | undefined;
             } while (pageKey);
         } finally {
-            this.#emitMutation(opts, namespace, [], 'flush');
+            this.#emitMutation(actor, namespace, [], 'flush');
         }
 
         return { res: true, usage };
@@ -2797,7 +2651,7 @@ export class SystemKVStore extends PuterStore {
         const probeUsage = await this.#assertNotPrivate(namespace, key, opts);
         const { usage, isPrivate } = await this.rawExpireAt(namespace, key, ts);
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'expire',
@@ -2827,7 +2681,7 @@ export class SystemKVStore extends PuterStore {
             timestamp,
         );
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'expire',
@@ -2959,7 +2813,7 @@ export class SystemKVStore extends PuterStore {
             throw pathWriteError(e, 'incr', key, paths);
         }
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'set',
@@ -3095,7 +2949,7 @@ export class SystemKVStore extends PuterStore {
             throw pathWriteError(e, 'add', key, paths);
         }
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'set',
@@ -3174,7 +3028,7 @@ export class SystemKVStore extends PuterStore {
                 };
             }
             await this.#committed(
-                opts,
+                actor,
                 namespace,
                 [key],
                 'set',
@@ -3320,7 +3174,7 @@ export class SystemKVStore extends PuterStore {
         }
 
         await this.#committed(
-            opts,
+            actor,
             namespace,
             [key],
             'set',

src/backend/stores/systemKv/kvMutationEvents.test.ts

@@ -101,7 +101,6 @@ describe('what a mutation announces', () => {
             keys: [KEY],
             op: 'set',
             values: [1],
-            actingUserId: 42,
         });
         expect(mutations()[0].key).toBe('kv.mutated');
     });
@@ -280,54 +279,10 @@ describe('flush', () => {
         expect(mutations()[0].data).toEqual({
             namespace: namespaceOf(),
             userId: 42,
-            actingUserId: 42,
         });
     });
 });
 
-describe('who made the change', () => {
-    it('keys a write into another user`s namespace on its owner, naming the writer', async () => {
-        const ownerUuid = `owner-${Math.random().toString(36).slice(2)}`;
-        await store.set(
-            { key: KEY, value: 1 },
-            {
-                actor,
-                namespaceUser: { uuid: ownerUuid, id: 7 },
-                namespaceAppUuid: KV_GLOBAL_APP_KEY,
-            },
-        );
-
-        expect(onlyMutation()).toMatchObject({
-            namespace: `v1:${ownerUuid}:${KV_GLOBAL_APP_KEY}`,
-            userId: 7,
-            actingUserId: 42,
-        });
-        expect(onlyMutation()).not.toHaveProperty('viaWorker');
-    });
-
-    it.each([
-        ['a worker session', { session: { uid: 's-1', kind: 'worker' } }],
-        ['an events handler', { handlerDepth: 1 }],
-    ])(
-        'marks a write made by %s, on writes and flushes alike',
-        async (_name, extra) => {
-            const server = { ...actor, ...extra } as Actor;
-            await store.set({ key: KEY, value: 1 }, { actor: server });
-            expect(onlyMutation()).toMatchObject({
-                actingUserId: 42,
-                viaWorker: true,
-            });
-
-            emitted = [];
-            await store.flush({ actor: server });
-            expect(mutations()[0].data).toMatchObject({
-                actingUserId: 42,
-                viaWorker: true,
-            });
-        },
-    );
-});
-
 describe('who is left out', () => {
     it('says nothing for internal system data', async () => {
         await store.set({ key: KEY, value: 1 }, { actor: SYSTEM_ACTOR });

src/backend/types.ts

@@ -1268,19 +1268,6 @@ interface IConfigOptional {
         internalSecret?: string;
     };
 
-    /**
-     * Key-value sharing beyond watching.
-     *
-     * - `shareHandles` — whether a share handle may carry `read` or `write`
-     *   access, and be used for key-value calls. Absent means off: those mints
-     *   and upgrades reject with `kv_handles_disabled`. Watch-only handles stay
-     *   under `events.kvHandles`, and revoking, unsharing and listing are never
-     *   gated.
-     */
-    kv?: {
-        shareHandles?: boolean;
-    };
-
     /**
      * Display multiplier converting metered amounts into the "credits" clients
      * show. Applied server-side by the usage-reporting endpoints, so raw

src/backend/util/pagination.test.ts

@@ -8,7 +8,6 @@ import {
     openCursor,
     openIdCursor,
     sealCursor,
-    unsealCursor,
 } from './pagination';
 import { HttpError } from '../core/http';
 
@@ -108,30 +107,6 @@ describe('pagination util', () => {
             expect(plain).toBe(encodeCursor({ id: 3 }));
             expect(openCursor(plain, undefined)).toEqual({ id: 3 });
         });
-
-        it('pads to one length whatever the payload holds', () => {
-            const short = sealCursor({ k: 'a' }, SECRET, { padTo: 256 })!;
-            const long = sealCursor({ k: 'a'.repeat(200) }, SECRET, {
-                padTo: 256,
-            })!;
-            expect(short.length).toBe(long.length);
-            expect(unsealCursor(short, SECRET)).toEqual({ k: 'a' });
-            expect(openCursor(long, SECRET)).toEqual({ k: 'a'.repeat(200) });
-            // Past the size, the next multiple rather than a cut.
-            const over = sealCursor({ k: 'a'.repeat(300) }, SECRET, {
-                padTo: 256,
-            })!;
-            expect(Buffer.from(over, 'base64url').length).toBe(
-                Buffer.from(short, 'base64url').length + 256,
-            );
-        });
-
-        it('opens only what it sealed with unsealCursor', () => {
-            expect(unsealCursor(encodeCursor({ id: 7 })!, SECRET)).toBeNull();
-            expect(
-                unsealCursor(sealCursor({ id: 7 }, 'other-secret')!, SECRET),
-            ).toBeNull();
-        });
     });
 
     describe('normalizeLimit', () => {

src/backend/util/pagination.ts

@@ -93,29 +93,20 @@ const sealKey = (secret: string): Buffer => {
  * A cursor its holder cannot read, for keysets over a global sequence: a plain
  * one would let two pages show how fast the whole table grows. Encrypted and
  * authenticated, so an altered cursor is refused like any malformed one.
- * Without a secret it is a plain `encodeCursor` cursor. `padTo` rounds the
- * plaintext up to a multiple of that many bytes, so the length hides the size.
+ * Without a secret it is a plain `encodeCursor` cursor.
  */
 export const sealCursor = (
     payload: Record<string, unknown> | undefined,
     secret: string | undefined,
-    { padTo }: { padTo?: number } = {},
 ): string | undefined => {
     if (!payload || Object.keys(payload).length === 0) return undefined;
     if (!secret) return encodeCursor(payload);
-    let plain = Buffer.from(JSON.stringify(payload), 'utf8');
-    if (padTo) {
-        // Trailing spaces, which JSON.parse skips.
-        const padded = Buffer.alloc(
-            Math.ceil(plain.length / padTo) * padTo,
-            ' ',
-        );
-        plain.copy(padded);
-        plain = padded;
-    }
     const iv = randomBytes(SEAL_IV_BYTES);
     const cipher = createCipheriv('aes-256-gcm', sealKey(secret), iv);
-    const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+    const body = Buffer.concat([
+        cipher.update(JSON.stringify(payload), 'utf8'),
+        cipher.final(),
+    ]);
     return Buffer.concat([
         Buffer.from([SEALED_CURSOR_VERSION]),
         iv,
@@ -124,8 +115,7 @@ export const sealCursor = (
     ]).toString('base64url');
 };
 
-/** What `sealCursor` sealed under `secret`, or null if `cursor` is not that. */
-export const unsealCursor = (
+const unsealCursor = (
     cursor: string,
     secret: string,
 ): Record<string, unknown> | null => {

src/docs/src/Email/get.md

@@ -6,7 +6,7 @@ platforms: [websites, apps, nodejs, workers]
 
 Reads one message by the `id` a listing returned. The whole raw message is downloaded and parsed, so the result carries the full subject, sender and recipients, the text and HTML bodies, every header, and each attachment with its bytes. Pass `raw: true` to get the unparsed `message/rfc822` bytes as a `Blob` instead.
 
-Reading the mailbox requires read access to the `~/.mail` folder, the same grant [`puter.email.list()`](/Email/list/) needs.
+Reading the mailbox requires the `fs:/{username}/.mail:read` permission, the same grant [`puter.email.list()`](/Email/list/) needs.
 
 ## Syntax
 

src/docs/src/Email/list.md

@@ -6,11 +6,7 @@ platforms: [websites, apps, nodejs, workers]
 
 Lists the messages in one folder of the user's mailbox, newest first. Every call returns one page of `items` plus, while more pages exist, a `cursor` to pass back for the next one. Listing reads the mailbox's folder structure only, so it never downloads a message: each item carries the subject, date, and size, and `puter.email.get()` fetches the rest.
 
-The mailbox belongs to the user, so it is protected like the rest of their files. An app reads it only after the user grants read access to the `~/.mail` folder. To ask for it, call [`puter.perms.request()`](/Perms/request/):
-
-```js
-await puter.perms.request('fs', { path: '~/.mail', access: 'read' });
-```
+The mailbox belongs to the user, so it is protected like the rest of their files. An app reads it only after the user grants `fs:/{username}/.mail:read`, for example with `puter.perms.request('permission', { permission: `fs:/${username}/.mail:read` })`.
 
 ## Syntax
 

src/docs/src/Events.md

@@ -22,7 +22,7 @@ What you watch is written as a subject string:
 | `kv:cart` | One key in your app's key-value store (`kv:cart*` for a prefix) |
 | `notif:app-user` | Notifications about the user's use of your app |
 
-See [Subjects and events](/Events/subjects/) for the full subject syntax, the event shape, and how to watch key-value data another user shared with you.
+See [Subjects and events](/Events/subjects/) for the full subject syntax, the event shape, and how to share key-value events with another user.
 
 With the [User-Pays Model](/user-pays-model/), deliveries are billed to the user holding the subscription, not to you. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events) for limits and costs.
 

src/docs/src/Events/fetch.md

@@ -48,7 +48,7 @@ Each item is a notification event:
 | `type` | String | The kind of notification, from the published catalog: `share.received`, `app.worker.deployed`, and so on. |
 | `audience` | String | `account`, `developer`, or `app-user`. |
 | `appUid` | String \| null | The app it's about, or `null` for platform notifications. |
-| `notification` | Object | The stored payload. It always has `type`, and every type except `kv.share.received` has a `title`. Other fields depend on `type` (below). |
+| `notification` | Object | The stored payload. It always has `type`, and everything Puter sends has a `title`; other fields depend on `type` (below). |
 | `self` | Boolean | Always `true`: a mailbox is your own. |
 | `ts` | Number | When it was created, in milliseconds since the epoch. |
 | `seq` | Number | Position within the page. |
@@ -60,7 +60,6 @@ Besides `type` and `title`, `notification` carries:
 - `app.worker.deployed`, `app.worker.deployFailed`: nothing else.
 - `app.events.ended`: `reason` (`anchor_deleted`, `permission_revoked`, or `no_credit`); `anchor_deleted` and `permission_revoked` also add `subject`, `subjects` (up to 20) and `count`.
 - `app.events.suspended`: `handler` and `subscriptions`.
-- `kv.share.received`: `handle`, `access`, `label`, and `createdAt` (in Unix seconds) of a key-value share another user made with you (see [`puter.kv.listShared()`](/KV/listShared/)). It arrives on `notif:app-user` in the app whose data was shared, and the Puter desktop doesn't show it. Outside that app, `notif:app-user` leaves it out. `notif:<appId>:app-user` returns it to the account itself and to that app, and not to other apps.
 
 Other notifications can carry other fields, so read them defensively.
 

src/docs/src/Events/onLocal.md

@@ -57,7 +57,7 @@ The promise rejects with `{ message, code }`:
 | `invalid_kv_handle_key` | A `kv:<handle>:…` subject names no key, or a key that tries to leave the shared region. |
 | `invalid_include_value` | `includeValue` isn't a boolean, or the subject isn't `kv:`. |
 | `events_cross_app_disabled` | The subject names another app's key-value data, and that's turned off on this server. |
-| `forbidden` | The other app doesn't share its data, or your app hasn't been granted read access to its key-value data (see [`puter.perms.request('appData')`](/Perms/appData/)). |
+| `forbidden` | The other app doesn't share its data, or your app hasn't been granted `app-data:<appId>:kv:read`. |
 | `subject_does_not_exist` | The subject doesn't exist, or this account can't read it. |
 | `events_subscription_limit` | This connection already has 50 subscriptions. |
 | `too_many_requests` | Over the subscribe rate limit. |

src/docs/src/Events/onPersistent.md

@@ -35,10 +35,10 @@ puter.events.onPersistent(options)
 
 ## Background delivery needs consent
 
-Running your handler while the user isn't there needs its own per-app permission, **`events:background`**. Subscribing with `worker` among the `targets` (the default for an app) without it fails with `events_background_consent_required`. To ask for it, call [`puter.perms.request()`](/Perms/request/) with the `'backgroundEvents'` resource:
+Running your handler while the user isn't there needs its own per-app permission, **`events:background`**. Subscribing with `worker` among the `targets` (the default for an app) without it fails with `events_background_consent_required`. Request it like any other permission:
 
 ```js
-await puter.perms.request('backgroundEvents');
+await puter.perms.request(['events:background']);
 ```
 
 The user can revoke it wherever they manage the app's access. That suspends every worker-target subscription the app holds for them with `permission_revoked`, and granting it again doesn't resume them: subscribe again. A subscription that only wants deliveries while your app is open needs no consent: pass `targets: ['socket']`.

src/docs/src/Events/subjects.md

@@ -98,50 +98,49 @@ Watching another app's key-value data takes the same consent as reading it: the
 
 Entries the other app wrote with `disableSharing` are never delivered. Marking a key private produces no event, so a value you already have for it may be stale.
 
-<a id="sharing-key-value-events-with-another-user"></a>
+## Sharing key-value events with another user
 
-## Sharing key-value data with another user
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-`kv:` always means your own data. When another user shares part of theirs with you using [`puter.kv.share()`](/KV/share/), you watch it through the share's **handle**, which goes where an app id would go. For a walkthrough, see [Send Live Updates to Other Users](/recipes/send-live-updates-to-other-users/).
+`kv:` always means your own data. To let another account watch part of yours, mint a **share handle** over a key prefix and give it to them. They subscribe with the handle where an app id would go:
 
 ```js
-// The owner shares one workspace with another user.
-await puter.kv.share(`workspace:${workspaceId}:`, 'bob', 'watch');
+// The owner shares one workspace with another account.
+const res = await fetch(`${puter.APIOrigin}/events/kv-handles`, {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${puter.authToken}`,
+    },
+    body: JSON.stringify({
+        granteeUsername: 'bob',
+        // Use a segment you'll never rename: the handle is fixed to this prefix.
+        prefix: `workspace:${workspaceId}:`,
+    }),
+});
+const { handle } = await res.json();
 ```
 
 ```js
-// Bob finds the share and watches every key written in that workspace.
+// Bob watches every key written in that workspace.
 // `event.key` is relative to the handle: `messages:1`, not `workspace:<id>:messages:1`.
-const { items } = await puter.kv.listShared();
-const { handle } = items[0];
 await puter.events.onLocal(`kv:${handle}:*`, ({ event }) => render(event.key));
 ```
 
-- **Every level can watch.** A share has `watch`, `read`, or `write` access, and all three can subscribe. With `watch`, the holder only gets events. With `read`, they can also read the keys with [`puter.kv.get()`](/KV/get/) and [`puter.kv.list()`](/KV/list/), passing the handle, to catch up after a [gap](#gaps) or to read a value an event left out. With `write`, they can also change and delete the keys. [Sharing with other users](/KV/#sharing-with-other-users) covers the levels.
-- **The holder learns only the handle.** It doesn't say whose data it is or where it sits. The `subject` and `key` in their deliveries are relative to the handle. `kv:<handle>:messages:*` narrows to part of the shared region.
-- **Values.** `includeValue` works through a handle, with the same limits.
+- **The holder learns only the handle**: not whose data it is, where it sits, or anything above the prefix. `subject` and `key` in their deliveries are relative to the handle. `kv:<handle>:messages:*` narrows to part of the shared region.
+- **Values:** `includeValue` works through a handle, with the same limits. A handle grants events, not reads, so when a value is left out the holder needs some other authorized way to read it.
 - **Private entries stay private.** An entry written with `disableSharing` is never delivered through a handle: no event, key, or value.
+- **Use a stable prefix.** A handle stays on the prefix it was minted on. Rename `workspace:<uuid>:` to `project:<uuid>:` and existing handles point at keys nothing writes. Prefer synthetic ids (`workspace:<uuid>:`, `thread:<uuid>:`) over names that might change (`acme-corp:`).
+- **Prefixes are literal.** `*`, `?` and empty segments (`workspace::abc:`) are refused with `invalid_kv_share_prefix`. The trailing `:` is optional.
 - **Keys can't leave the handle.** A handle with no key after it, or a key using `..`, is refused with `invalid_kv_handle_key`.
-- **Writes from every side arrive.** A change the owner makes, and a change any holder makes through a `write` share, reach the owner's subscriptions and every holder's. On a holder's own write through the handle, `self` is `true`, so `self && !viaWorker` skips your own changes. See [the event](#the-event).
 
-When a share stops, deliveries through its handle stop, and every persistent subscription on it is suspended with `permission_revoked` and its backlog dropped. If another share to the same holder still covers its keys, live deliveries through the stopped handle can continue for up to 60 seconds. This happens when the owner revokes it with [`puter.kv.unshare()`](/KV/unshare/), when the holder removes their own access the same way, and when the app whose data it is gets deleted. Where `watch` shares are off on the deployment, handle subjects fail with `events_kv_handles_disabled`.
+**Managing handles.** `GET /events/kv-handles` lists the handles the account has minted, revoked ones included. `DELETE /events/kv-handles/<handle>` revokes one, and every persistent subscription on it is suspended with `permission_revoked` and its backlog dropped. Revoking an already-revoked handle isn't an error. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events) for how many handles an account can hold. Temporary accounts can't mint handles (`events_kv_handle_requires_account`). Where the feature is off, minting and handle subjects fail with `events_kv_handles_disabled`.
 
-**Apps.** An app can share, list, and unshare its user's data with [`puter.kv.share()`](/KV/share/) and its sibling methods, but only inside its own namespace and with the user's consent. To ask for it, call [`puter.perms.request()`](/Perms/request/) with the `'kvShare'` resource, the prefix the shares will cover, and the highest level they'll have:
-
-```js
-await puter.perms.request('kvShare', { prefix: 'workspace:abc:', access: 'watch' });
-```
-
-The consent covers that prefix and every key under it, at that level and the levels below it. It must name a prefix. A prefix that covers the whole namespace is rejected with `invalid_argument`. An app that lists shares sees only its own namespace.
+**Apps.** An app can mint, list and revoke handles for its user, but only inside its own namespace and with the user's consent: `manage:kv-share:<userUuid>:<appId>:<prefix>`, requested with [`puter.perms.request()`](/Perms/request/). The prefix supplies its segments, so `workspace:abc:` ends the permission as `…:workspace:abc`. The consent must name a prefix; asking for the whole namespace is refused with `invalid_kv_share_prefix`. An app that lists handles sees only its own namespace.
 
 | Refused with | When |
 | --- | --- |
-| `events_kv_handle_not_delegated` | Sharing or revoking outside the consented prefix or level, or after the consent was withdrawn (the share stays in place). |
-| `events_kv_handle_outside_namespace` | Sharing outside the app's own namespace. |
-| `events_kv_handle_owner_only` | Listing or revoking from an access token the app issued, or revoking a share outside the app's namespace. |
-| `forbidden` | Sharing from an access token the app issued. |
+| `events_kv_handle_not_delegated` | Minting or revoking outside the consented prefix, or after the consent was withdrawn (the handle stays in place). |
+| `events_kv_handle_outside_namespace` | Minting outside the app's own namespace. |
+| `events_kv_handle_owner_only` | The caller is an access token the app issued, a different app of the same user, or the handle is outside the app's namespace. |
 
 An app can also subscribe through a handle, but only when the shared region belongs to that same app. A different app, even for the same user, is refused as if the handle didn't exist.
 
@@ -161,8 +160,7 @@ The handler is called with `{ event }`. A filesystem change carries:
 | `uid` | String | The uid of the node that changed. |
 | `path` | String | The path of the node that changed. |
 | `from` | String | On a `move`, the path the node left. Only present when the subscription was watching that location. |
-| `self` | Boolean | `true` when the account holding the subscription made the change. |
-| `viaWorker` | Boolean | `true` when the change came from server-side code running as an account, such as a worker using `me.puter` or an [events handler](/Events/handlers/) running in the events worker. A worker using `user.puter` acts as the user who called it, so its changes are that user's own, with `viaWorker` set to `false`. A handler running in a client writes as that client, also with `viaWorker` set to `false`. Skip your own changes with `self && !viaWorker`, which still lets through the ones a worker made as your account. |
+| `self` | Boolean | `true` when the account holding the subscription made the change. Use it to ignore your own writes. |
 | `ts` | Number | When it happened, in milliseconds since the epoch. |
 | `seq` | Number | Position within one dispatch, when a change goes to several subscriptions. |
 
@@ -171,12 +169,11 @@ A key-value change carries `key` instead of `uid` and `path`, and different ops:
 | Field | Type | Description |
 | --- | --- | --- |
 | `id` | String | Unique id for the event. |
-| `subject` | String | `kv:<appId>:<key>`, naming the key that changed. Through a share, `kv:<handle>:<key>`. |
+| `subject` | String | `kv:<appId>:<key>`, naming the key that changed. |
 | `op` | String | `set` for a write, `del` for a removal, `expire` when only the key's lifetime changed. |
 | `key` | String | The key that changed. |
 | `value` | Any | The new value (`null` on a `del`). Only with `includeValue`, and only within the [limits above](#getting-the-new-value). Never on an `expire`. |
 | `self` | Boolean | As above. |
-| `viaWorker` | Boolean | As above. |
 | `ts` | Number | As above. |
 | `seq` | Number | As above. |
 

src/docs/src/KV.md

@@ -9,7 +9,7 @@ It supports various operations such as set, get, delete, list keys, increment an
 
 Puter.js handles all the infrastructure for you, so you don't need to set up servers, handle scaling, or manage backups. And thanks to the [User-Pays Model](/user-pays-model/), you don't have to worry about storage, read, or write costs, as users of your application cover their own usage.
 
-<div class="info"><strong>Need to share data across users?</strong> Each user's key-value store lives in their own account. A user can share part of theirs with another user, as described in <a href="#sharing-with-other-users">Sharing with other users</a>. To keep a single, centralized store that every user reads from and writes to, use a <a href="/Workers/">Serverless Worker</a>. Its code can act on the worker owner's resources, giving all users one shared backend.</div>
+<div class="info"><strong>Need to share data across users?</strong> Each user's key-value store lives in their own account, so one user can't read another's data. To keep a single, centralized store that every user reads from and writes to, use a <a href="/Workers/">Serverless Worker</a> — its code can act on the worker owner's resources, giving all users one shared backend.</div>
 
 ## Features
 
@@ -223,74 +223,9 @@ These Key-Value Store features are supported out of the box when using Puter.js:
 - **[`puter.kv.expireAt()`](/KV/expireAt/)** - Set key expiration timestamp
 - **[`puter.kv.list()`](/KV/list/)** - List keys in ascending or descending order
 - **[`puter.kv.flush()`](/KV/flush/)** - Clear all data
-- **[`puter.kv.share()`](/KV/share/)** - Share the keys under a prefix with another user
-- **[`puter.kv.unshare()`](/KV/unshare/)** - Stop a share, as its owner or its holder
-- **[`puter.kv.listShared()`](/KV/listShared/)** - List the shares other users made with you
-- **[`puter.kv.listSharedByMe()`](/KV/listSharedByMe/)** - List the shares you made
 - **[`puter.kv.MAX_KEY_SIZE`](/KV/MAX_KEY_SIZE/)** - Maximum key size in bytes
 - **[`puter.kv.MAX_VALUE_SIZE`](/KV/MAX_VALUE_SIZE/)** - Maximum value size in bytes
 
-## Sharing with other users
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-A user can share the keys under a prefix with another Puter user. The user who shares is the share's owner, and the user it's shared with is its holder. The keys stay in the owner's store.
-
-Pick the tool by what you want to do:
-
-| You want to… | Use |
-| --- | --- |
-| Let another user see or change part of your app's data | [`puter.kv.share()`](/KV/share/) |
-| Let another app of the same user use your data | [`puter.perms.request('appData', …)`](/Perms/appData/) |
-| Share files | [`puter.fs.share()`](/FS/share/) |
-| Show data to anyone, signed in or not | [Hosting](/Hosting/) or a [worker](/Workers/). A share is for one user, who needs a Puter account. |
-| Enforce rules per writer, such as letting each user edit only their own posts | A prefix per writer, each shared separately, or a [worker](/Workers/) that checks each write |
-
-A share has one of three levels, and each includes the ones before it:
-
-- **`watch`**: the holder gets [events](/Events/subjects/#sharing-key-value-data-with-another-user) when keys under the prefix change.
-- **`read`**: the holder can also [`get()`](/KV/get/) and [`list()`](/KV/list/) keys.
-- **`write`**: the holder can also change keys with every other method. Write includes delete, so every holder with write access can change or remove any key under the prefix.
-
-An app shares its user's data only with that user's consent, asked once with [`puter.perms.request('kvShare', …)`](/Perms/request/) at the level it will share or higher. Without it, [`puter.kv.share()`](/KV/share/) fails with `events_kv_handle_not_delegated`.
-
-The holder finds the share with [`puter.kv.listShared()`](/KV/listShared/), and passes its `handle` to the other methods. Keys are relative to the shared prefix. Here the owner writes `list:<id>:meta`, and the holder reads the same key as `meta`:
-
-```js
-// The owner, once per app: let this app share `list:` keys with write access
-await puter.perms.request('kvShare', { prefix: 'list:', access: 'write' });
-
-const prefix = `list:${crypto.randomUUID()}:`;
-await puter.kv.set(`${prefix}meta`, { title: 'Groceries' });
-await puter.kv.share(prefix, 'alice', 'write');
-
-// Alice, in the same app
-const { items } = await puter.kv.listShared();
-const { handle } = items[0];
-const meta = await puter.kv.get('meta', { handle });
-await puter.kv.set(`item:${crypto.randomUUID()}`, { text: 'milk' }, { handle });
-const entries = await puter.kv.list('item:*', true, { handle });
-```
-
-- **What the holder knows.** A share tells the holder its level, its app, and an optional label. It never says who shared it or what the prefix is. The label is plain text the owner sets with [`puter.kv.share()`](/KV/share/). Render it with `textContent`, never as HTML.
-- **Notification.** When a user shares an app's data, the holder gets a `kv.share.received` notification in that app, on [`notif:app-user`](/Events/subjects/#notifications). It carries the `handle`, `access`, `label`, and `createdAt`. Listen for it with [`puter.events.onLocal()`](/Events/onLocal/), or read missed ones with [`puter.events.fetch()`](/Events/fetch/). The Puter desktop doesn't show it, so your app is where the holder finds out about the share. The live notification needs notifications to be turned on for events on the deployment. Calling [`puter.kv.listShared()`](/KV/listShared/) when your app opens finds new shares in every case.
-- **Blocks.** A user who blocked the owner, or who doesn't accept shares from anyone, can't be shared with, and [`puter.kv.share()`](/KV/share/) fails with `recipient_not_accepting_shares`.
-- **Account.** Sharing needs a confirmed email address where the deployment requires one, and no phone number, card, or paid plan.
-- **Private entries.** Entries written with `disableSharing` aren't readable or listed through a share. Writing to one through a share is refused, so a holder with write access can learn that a private key exists, but never its value. Keep private entries outside the prefixes you share.
-- **Writes from several users.** When two users write the same key at about the same time, the last write wins. For a log of changes, write each change to its own key, such as `chg:<timestamp>-<random>`, instead of updating one shared counter.
-- **Cost.** Each user pays for their own reads and writes, including the ones they make through a share.
-
-Either side ends a share with [`puter.kv.unshare()`](/KV/unshare/). See [Rate Limits and Quotas](/rate-limits-and-quotas/#events) for how many shares an account can make and hold.
-
-These recipes show sharing in a full app:
-
-- [Share a List With Someone](/recipes/share-a-list-with-someone/)
-- [Let Someone View Your Data](/recipes/let-someone-view-your-data/)
-- [Send Live Updates to Other Users](/recipes/send-live-updates-to-other-users/)
-- [Manage Who Has Access to Shared Data](/recipes/manage-who-has-access-to-shared-data/)
-- [Build a Group Chat](/recipes/build-a-group-chat/)
-- [Share Data From Your Backend](/recipes/share-data-from-your-backend/)
-
 ## Examples
 
 You can see various Puter.js Key-Value Store features in action from the following examples:

src/docs/src/KV/add.md

@@ -11,7 +11,6 @@ Add values to an existing key. When you pass an array, its elements are appended
 ```js
 puter.kv.add(key, value)
 puter.kv.add(key, pathAndValue)
-puter.kv.add(key, value, optConfig)
 ```
 
 ## Parameters
@@ -36,17 +35,6 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s
 
 A plain object is read as a path map, never appended as an element: to append an object, wrap it in an array, as in `puter.kv.add('log', [{ at, event }])`.
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
-Pass `optConfig` after `value`, as in `puter.kv.add('tags', ['new'], { handle })`. An object in the place of `value` is read as a path map.
-
 ## Return value
 
 Returns a `Promise` that resolves to the updated value stored at `key`.
@@ -69,11 +57,6 @@ A rejection carries an `Error` with a stable `code`:
 | `subject_does_not_exist` | `optConfig.appUuid` names an app that doesn't exist. |
 | `response_timeout` | Too many writers on the key right now — retry. |
 | `too_many_requests` | The rate limit was exceeded. See [Rate Limits and Quotas](/rate-limits-and-quotas/). |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
 
 ## Examples
 

src/docs/src/KV/decr.md

@@ -12,7 +12,6 @@ Decrements the value of a key. A missing or expired key starts from 0 and loses
 puter.kv.decr(key)
 puter.kv.decr(key, amount)
 puter.kv.decr(key, pathAndAmount)
-puter.kv.decr(key, amount, optConfig)
 ```
 
 ## Parameters
@@ -34,17 +33,6 @@ When `amount` is an object: Decrements a property within an object value stored
 
 Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `some.path[1].to.value`), and quoted property names (`["key.with.dots"]`). An empty path (`""`) targets the whole stored value. Use non-negative integer indexes in brackets to address arrays. When a path continues through an array element (for example, `[0].score`), that element must already exist. Missing object parents are created automatically; sparse array elements are not created. A path may chain at most 31 levels; a deeper one rejects with `bad_request`. Quoted names can't be empty. All of a call's paths go into one write, so a call fits at most 1,500 path segments and, with short field names, about 60 paths; split larger changes across calls. See [Rate Limits and Quotas](/rate-limits-and-quotas/).
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
-Pass `optConfig` after `amount`, as in `puter.kv.decr('stats', 1, { handle })`. An object in the place of `amount` is read as a path map.
-
 ## Return Value
 
 Returns the new value of the key after the decrement operation — a number for the plain form, or the whole stored value when `amount` is a path map.
@@ -67,11 +55,6 @@ A rejection carries an `Error` with a stable `code`:
 | `subject_does_not_exist` | `optConfig.appUuid` names an app that doesn't exist. |
 | `response_timeout` | Too many writers on the key right now — retry. |
 | `too_many_requests` | The rate limit was exceeded. See [Rate Limits and Quotas](/rate-limits-and-quotas/). |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
 
 ## Examples
 

src/docs/src/KV/del.md

@@ -9,37 +9,15 @@ When passed a key, will remove that key from the key-value storage. If there is
 ## Syntax
 ```js
 puter.kv.del(key)
-puter.kv.del(key, optConfig)
 ```
 
 ## Parameters
 #### `key` (String) (required)
 A string containing the name of the key you want to remove.
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 ## Return value 
 A `Promise` that will resolve to `true` when the key has been removed.
 
-## Errors
-
-With `handle`, the promise can reject with these codes:
-
-| Code | Meaning |
-| -- | -- |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
-
 ## Examples
 
 <strong class="example-title">Delete the key 'name'</strong>

src/docs/src/KV/expire.md

@@ -10,7 +10,6 @@ Set the time-to-live (TTL) in seconds for a key in the key-value store.
 
 ```js
 puter.kv.expire(key, ttlSeconds)
-puter.kv.expire(key, ttlSeconds, optConfig)
 ```
 
 ## Parameters
@@ -23,31 +22,10 @@ A string containing the name of the key.
 
 The number of seconds until the key is removed from the key-value store. `0` or less expires the key immediately.
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 ## Return value
 
 A `Promise` that will resolve to `true` when the expiration has been set.
 
-## Errors
-
-With `handle`, the promise can reject with these codes:
-
-| Code | Meaning |
-| -- | -- |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
-
 ## Keys That Don't Exist
 
 A missing or already-expired key becomes an empty entry with the TTL you gave it, rather than staying absent. [`puter.kv.list()`](/KV/list/) shows it and [`puter.kv.get()`](/KV/get/) reads it as `null`, the same as a missing key — the old value, if there was one, never comes back. [`puter.kv.incr()`](/KV/incr/) rejects such an entry, the same as any non-number value.

src/docs/src/KV/expireAt.md

@@ -10,7 +10,6 @@ Set the expiration timestamp (in seconds) for a key in the key-value store.
 
 ```js
 puter.kv.expireAt(key, timestampSeconds)
-puter.kv.expireAt(key, timestampSeconds, optConfig)
 ```
 
 ## Parameters
@@ -23,31 +22,10 @@ A string containing the name of the key.
 
 The Unix timestamp (in seconds) at which the key will be removed from the key-value store. Use seconds, not the milliseconds `Date.now()` returns. A timestamp at or before now, including `0`, expires the key immediately.
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 ## Return value
 
 A `Promise` that will resolve to `true` when the expiry time has been set.
 
-## Errors
-
-With `handle`, the promise can reject with these codes:
-
-| Code | Meaning |
-| -- | -- |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
-
 ## Keys That Don't Exist
 
 A missing or already-expired key becomes an empty entry with the TTL you gave it, rather than staying absent. [`puter.kv.list()`](/KV/list/) shows it and [`puter.kv.get()`](/KV/get/) reads it as `null`, the same as a missing key — the old value, if there was one, never comes back. [`puter.kv.incr()`](/KV/incr/) rejects such an entry, the same as any non-number value.

src/docs/src/KV/flush.md

@@ -17,10 +17,6 @@ None
 ## Return value
 A `Promise` that will resolve to `true` when the key-value store has been flushed (emptied), or reject with an error on failure.
 
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-Flushing works only on your own store. Passing the `handle` of data another user shared with you is rejected with `kv_handle_option_invalid`. To clear a shared prefix, delete its keys with [`puter.kv.del()`](/KV/del/).
-
 ## Examples
 
 ```html;kv-flush

src/docs/src/KV/get.md

@@ -9,37 +9,15 @@ When passed a key, will return that key's value, or `null` if the key does not e
 ## Syntax
 ```js
 puter.kv.get(key)
-puter.kv.get(key, optConfig)
 ```
 
 ## Parameters
 #### `key` (String) (required)
 A string containing the name of the key you want to retrieve the value of.
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `read` or `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 ## Return value 
 A `Promise` that will resolve to the key's value. If the key does not exist or has expired, it will resolve to `null`. An empty marker left by [`puter.kv.expire()`](/KV/expire/) or [`puter.kv.expireAt()`](/KV/expireAt/) also reads as `null`.
 
-## Errors
-
-With `handle`, the promise can reject with these codes:
-
-| Code | Meaning |
-| -- | -- |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
-
 ## Examples
 
 <strong class="example-title">Retrieve the value of key 'name'</strong>

src/docs/src/KV/incr.md

@@ -12,7 +12,6 @@ Increments the value of a key. A missing or expired key starts from 0 and loses
 puter.kv.incr(key)
 puter.kv.incr(key, amount)
 puter.kv.incr(key, pathAndAmount)
-puter.kv.incr(key, amount, optConfig)
 ```
 
 ## Parameters
@@ -34,17 +33,6 @@ When `amount` is an object: Increments a property within an object value stored
 
 Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `some.path[1].to.value`), and quoted property names (`["key.with.dots"]`). An empty path (`""`) targets the whole stored value. Use non-negative integer indexes in brackets to address arrays. When a path continues through an array element (for example, `[0].score`), that element must already exist. Missing object parents are created automatically; sparse array elements are not created. A path may chain at most 31 levels; a deeper one rejects with `bad_request`. Quoted names can't be empty. All of a call's paths go into one write, so a call fits at most 1,500 path segments and, with short field names, about 60 paths; split larger changes across calls. See [Rate Limits and Quotas](/rate-limits-and-quotas/).
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
-Pass `optConfig` after `amount`, as in `puter.kv.incr('stats', 1, { handle })`. An object in the place of `amount` is read as a path map.
-
 ## Return Value
 
 Returns the new value of the key after the increment operation — a number for the plain form, or the whole stored value when `amount` is a path map.
@@ -67,11 +55,6 @@ A rejection carries an `Error` with a stable `code`:
 | `subject_does_not_exist` | `optConfig.appUuid` names an app that doesn't exist. |
 | `response_timeout` | Too many writers on the key right now — retry. |
 | `too_many_requests` | The rate limit was exceeded. See [Rate Limits and Quotas](/rate-limits-and-quotas/). |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
 
 ## Examples
 

src/docs/src/KV/list.md

@@ -15,9 +15,6 @@ puter.kv.list()
 puter.kv.list(pattern)
 puter.kv.list(returnValues = false)
 puter.kv.list(pattern, returnValues = false)
-puter.kv.list(pattern, optConfig)
-puter.kv.list(pattern, returnValues, optConfig)
-puter.kv.list(returnValues, optConfig)
 puter.kv.list(options)
 ```
 
@@ -33,15 +30,6 @@ If set, only keys that match the given pattern will be returned. The pattern is
 
 If set to `true`, the returned array will contain objects with both `key` and `value` properties. If set to `false`, the returned array will contain only the keys. Default is `false`.
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument of the positional forms. It takes these properties:
-
-- `handle` (String): List data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The share needs `read` or `write` access. The `pattern` is relative to the shared prefix and can be at most 768 bytes, and the returned keys are relative to the prefix too. The results and `total` leave out private entries. Every page of a full listing or a stream is fetched through the handle. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): List another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 #### `options` (Object) (optional)
 
 An object with the following optional properties:
@@ -54,7 +42,6 @@ An object with the following optional properties:
 - `offset` (Number): Skips the given number of items before the page starts. Not recommended — requests get slower and more expensive the larger the offset; prefer `cursor`. Maximum `5000`, and cannot be combined with `cursor`.
 - `includeTotal` (Boolean): If `true`, the result includes a `total` count of every item matching the query (across all pages). The count is metered and its cost grows with the size of your store — request it once (on the first page) and avoid it in hot paths. If you only need to know whether more pages exist, check for `cursor` instead of counting.
 - `fetchUntilFull` (Boolean): A page can come back with fewer than `limit` items even when more exist (for example when expired keys are excluded). If `true`, the page is filled up to `limit` items when possible. Requires `limit`.
-- `optConfig` (Object): Same as the `optConfig` parameter, as in `list({ pattern, optConfig: { handle } })`.
 - `stream` (Boolean): If `true`, the method returns an async iterator of [`KVListPage`](/Objects/kvlistpage) objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`.
 
 ## Return value
@@ -73,8 +60,6 @@ Invalid options, such as a non-boolean `reverse` or `offset` combined with `stre
 
 Without pagination params, the full listing is returned as a plain array. It reads the entire store and is metered per page, so on large stores a bare `list()` gets slow and costly. The SDK logs a one-time console warning when a full listing spans multiple pages. Use `stream: true` or `limit` and `cursor` pages instead, and narrow the scan with a `pattern`.
 
-With `handle`, the promise can also reject with `kv_handle_not_found` (the handle doesn't exist, the share stopped, or it isn't shared with you), `kv_handle_access_denied` (the share is `watch` only), `kv_handle_option_invalid` (`handle` combined with `appUuid`), `kv_handle_key_invalid` (`pattern` is over 768 bytes), or `kv_handles_disabled` (shares can't be used this way on this deployment).
-
 With `stream: true`, the method returns an async iterator of [`KVListPage`](/Objects/kvlistpage) objects instead:
 
 ```js

src/docs/src/KV/listShared.md

@@ -1,80 +0,0 @@
----
-title: puter.kv.listShared()
-description: List the key-value data other users have shared with you.
-platforms: [websites, apps, nodejs, workers]
----
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-Lists the live shares other users made with you, a page at a time. Each share comes with the `handle` you pass to the other [`puter.kv`](/KV/) methods to use it.
-
-A share tells you its level, its app, and the owner's label. It never says who shared it or what the prefix is. To tell shares apart, read the label, or read a key the owner keeps for that, such as `meta`, through the handle. Reading needs `read` or `write` access, so a `watch` share only has its label.
-
-In an app, the listing has only the shares of that app's data. Outside an app, it has every share made with you.
-
-## Syntax
-
-```js
-puter.kv.listShared()
-puter.kv.listShared(options)
-```
-
-## Parameters
-
-#### `options` (Object) (optional)
-
-- `limit` (Number): Shares per page. Defaults to `50`, at most `200`.
-- `cursor` (String): The `cursor` from the previous page.
-- `includeTotal` (Boolean): Add `total` to the result. Defaults to `false`.
-
-## Return value
-
-A `Promise` that resolves to:
-
-- `items` (Array): The shares on this page, oldest first. Each has:
-    - `handle` (String): Pass it as `handle` to use the share.
-    - `access` (String): `'watch'`, `'read'`, or `'write'`.
-    - `appUid` (String | null): The app whose data it is, or `null` for the store that belongs to no app.
-    - `label` (String | null): Plain text the owner set. Render it as text, with `textContent`, never as HTML.
-    - `createdAt` (Number): When the share was made, in Unix seconds.
-- `cursor` (String): Pass it as `cursor` to get the next page. It's included only if there are more pages to load.
-- `total` (Number): The number of live shares across every page. Only included when `includeTotal` is `true`.
-
-Shares that stopped aren't listed. An access token scoped to less than the account, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, gets an empty page.
-
-## Errors
-
-The promise rejects with `{ message, code }`. A `limit` that isn't a positive number is rejected with `bad_request`, and going over the rate limit with `too_many_requests`. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events).
-
-## Examples
-
-<strong class="example-title">Read every list shared with you</strong>
-
-```js
-const { items } = await puter.kv.listShared();
-for (const { handle, access, label } of items) {
-    // A watch share can't read keys, so it has only its label.
-    const meta = access === 'watch' ? null : await puter.kv.get('meta', { handle });
-    const row = document.createElement('li');
-    row.textContent = label ?? meta?.title ?? 'Shared list';
-    document.querySelector('#lists').append(row);
-}
-```
-
-<strong class="example-title">Page through every share</strong>
-
-```js
-let cursor;
-const all = [];
-do {
-    const page = await puter.kv.listShared({ limit: 50, cursor });
-    all.push(...page.items);
-    cursor = page.cursor;
-} while (cursor);
-```
-
-## Related
-
-- [`puter.kv.share()`](/KV/share/) - Share keys with another user
-- [`puter.kv.unshare()`](/KV/unshare/) - Remove your own access
-- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made

src/docs/src/KV/listSharedByMe.md

@@ -1,90 +0,0 @@
----
-title: puter.kv.listSharedByMe()
-description: List the key-value shares you made with other users, including ones that stopped.
-platforms: [websites, apps, nodejs, workers]
----
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-Lists the shares you made with [`puter.kv.share()`](/KV/share/), a page at a time. Shares that stopped stay in the listing with `revokedAt` and `revokedBy` set, as a record of who had access and when it ended.
-
-In an app, the listing has only the shares of that app's data. Outside an app, it has every share you made.
-
-## Syntax
-
-```js
-puter.kv.listSharedByMe()
-puter.kv.listSharedByMe(options)
-```
-
-## Parameters
-
-#### `options` (Object) (optional)
-
-- `limit` (Number): Shares per page. Defaults to `50`, at most `200`.
-- `cursor` (String): The `cursor` from the previous page.
-- `includeTotal` (Boolean): Add `total` to the result. Defaults to `false`.
-
-## Return value
-
-A `Promise` that resolves to:
-
-- `items` (Array): The shares on this page, oldest first. Each has:
-    - `handle` (String): The share's id.
-    - `prefix` (String): The shared prefix, ending with `:`.
-    - `access` (String): `'watch'`, `'read'`, or `'write'`.
-    - `appUid` (String | null): The app whose data is shared, or `null` for the store that belongs to no app.
-    - `holder` (String | null): The holder's username. When the holder deletes their account, their shares are deleted with it and leave this listing.
-    - `label` (String | null): The label the holder is shown.
-    - `createdAt` (Number): When the share was made, in Unix seconds.
-    - `revokedAt` (Number | null): When the share stopped, in Unix seconds, or `null` while it's live.
-    - `revokedBy` (String | null): Who stopped it. It's `'owner'` when you revoked it, `'holder'` when the holder removed their own access, and `'system'` when the app whose data it was got deleted. It's `null` while the share is live, and on some shares that stopped before Puter recorded who stopped them.
-- `cursor` (String): Pass it as `cursor` to get the next page. It's included only if there are more pages to load.
-- `total` (Number): The number of shares across every page, stopped ones included. Only included when `includeTotal` is `true`.
-
-## Errors
-
-The promise rejects with `{ message, code }`:
-
-| Code | Meaning |
-| -- | -- |
-| `events_kv_handle_owner_only` | The call came from an access token with less access than the account. |
-| `bad_request` | `limit` isn't a positive number. |
-| `too_many_requests` | Over the rate limit. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events). |
-
-## Examples
-
-<strong class="example-title">Show who has access, and who left</strong>
-
-```js
-const { items } = await puter.kv.listSharedByMe({ includeTotal: true });
-for (const share of items) {
-    const state = share.revokedBy === 'holder'
-        ? 'left'
-        : share.revokedAt
-            ? 'removed'
-            : share.access;
-    puter.print(`${share.holder}: ${share.prefix} (${state})<br>`);
-}
-```
-
-<strong class="example-title">Revoke everyone's access to one prefix</strong>
-
-```js
-let cursor;
-do {
-    const page = await puter.kv.listSharedByMe({ limit: 100, cursor });
-    for (const share of page.items) {
-        if (share.prefix === 'list:42:' && share.revokedAt === null) {
-            await puter.kv.unshare(share.handle);
-        }
-    }
-    cursor = page.cursor;
-} while (cursor);
-```
-
-## Related
-
-- [`puter.kv.share()`](/KV/share/) - Share keys with another user
-- [`puter.kv.unshare()`](/KV/unshare/) - Stop a share
-- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you

src/docs/src/KV/remove.md

@@ -10,7 +10,6 @@ Remove values from an existing key by path. Paths can target nested fields and a
 
 ```js
 puter.kv.remove(key, ...paths)
-puter.kv.remove(key, ...paths, optConfig)
 ```
 
 ## Parameters
@@ -25,15 +24,6 @@ One or more paths to remove (for example, `"profile.bio"`).
 
 Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `some.path[1].to.value`), and quoted property names (`["key.with.dots"]`). An empty path (`""`) deletes the whole entry, as [`puter.kv.del()`](/KV/del/) does, and resolves to `null`. Use non-negative integer indexes in brackets to address arrays. Removing an array element shifts later elements down by one index. A path may chain at most 31 levels; a deeper one rejects with `bad_request`. Quoted names can't be empty. All of a call's paths go into one write, so a call fits at most 1,500 path segments, and fewer when it has many paths or long ones; split larger changes across calls. See [Rate Limits and Quotas](/rate-limits-and-quotas/).
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 ## Return value
 
 Returns a `Promise` that resolves to the updated value stored at `key`. An expired key resolves to `null`. A call on another app's data with `optConfig.appUuid` also resolves to `null` when your app may delete that app's entries but not read them.
@@ -52,11 +42,6 @@ A rejection carries an `Error` with a stable `code`:
 | `forbidden` | Called with `optConfig.appUuid` for another app's data without permission, or the entry is private to that app. |
 | `subject_does_not_exist` | `optConfig.appUuid` names an app that doesn't exist. |
 | `too_many_requests` | The rate limit was exceeded. See [Rate Limits and Quotas](/rate-limits-and-quotas/). |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
 
 ## Examples
 

src/docs/src/KV/set.md

@@ -13,9 +13,7 @@ When passed a key and a value, will add it to the user's key-value store, or upd
 ```js
 puter.kv.set(key, value)
 puter.kv.set(key, value, expireAt)
-puter.kv.set(key, value, optConfig)
-puter.kv.set(key, value, expireAt, optConfig)
-puter.kv.set({ key, value, expireAt, optConfig })
+puter.kv.set({ key, value, expireAt })
 puter.kv.set([ { key, value, expireAt }, ... ])
 puter.kv.set({ items: [ { key, value, expireAt }, ... ] })
 ```
@@ -40,26 +38,12 @@ A Unix timestamp in seconds at which the key should expire. Omit it, or pass `nu
 
 #### `disableSharing` (Boolean) (optional)
 
-Pass inside the trailing options object, as in `set(key, value, { disableSharing: true })`, to mark this entry private to your app. A private entry cannot be read, listed, changed, or deleted by any other app, even one the user has granted access to your app's data with [`puter.perms.request('appData', …)`](/Perms/appData/). It is also hidden from another user you share its prefix with through [`puter.kv.share()`](/KV/share/). They can't read, list, or watch it, and a write to it through the share is refused. Use it for anything another app should never see, such as a cached access token. A user approving a request can't see what your store holds. It can't be combined with `appUuid` or `handle`.
+Pass inside the trailing options object — `set(key, value, { disableSharing: true })` — to mark this entry private to your app. A private entry cannot be read, listed, changed, or deleted by any other app, even one the user has granted access to your app's data with [`puter.perms.request('appData', …)`](/Perms/appData/). It is also not watched by other apps, or by another user through a [share handle](/Events/subjects/#sharing-key-value-events-with-another-user): those subscriptions get no event, key, or value for it. Use it for anything another app should never see, such as a cached access token: a user approving a request cannot see what your store holds.
 
 The batch form takes it too — `set([...items], { disableSharing: true })` marks every entry in the batch.
 
 Your own app reads and writes the entry normally. Writing the same key again without the flag makes it shareable once more, since `set` replaces the whole entry.
 
-#### `onlyIfAbsent` (Boolean) (optional)
-
-Pass inside the trailing options object, as in `set(key, value, { onlyIfAbsent: true })`, to write the key only when it has no live entry. An expired entry counts as absent. When a live entry holds the key, nothing is written and the promise resolves to `false`.
-
-Two writes at nearly the same time from different places may both succeed and both get `true`, and the later write wins. Use it to create something once where a rare double create is harmless, such as claiming a room id or setting up a new document. It isn't a lock, and it can't hand out unique numbers. For a log of changes, give each change its own key, such as `chg:<timestamp>-<writer>-<random>`, and order the changes by timestamp instead of using a shared counter. A counter kept with [`puter.kv.incr()`](/KV/incr/) has the same limit.
-
-The batch form rejects it with `invalid_request`.
-
-#### `handle` (String) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-Pass inside the trailing options object, as in `set(key, value, { handle })`, to write into data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). The batch form takes it too. With `handle`, a key can be at most 768 bytes.
-
 #### `items` (Array) (batch only)
 
 An array of `{ key, value, expireAt? }` objects, set in a single request. At most **1,000** items per call; a larger batch is rejected with `bad_request` and nothing is written. Each `key` is required and follows the same **1 KB** key / **400 KB** value limits. You can pass the array directly (`set([...])`) or wrapped in an object (`set({ items: [...] })`).
@@ -68,21 +52,7 @@ You may also pass a single object instead of positional arguments: `set({ key, v
 
 ## Return value
 
-A `Promise` that will resolve to `true` when the key-value pair has been created or the existing key's value has been updated. With `onlyIfAbsent`, it resolves to `false` when a live entry already held the key and nothing was written.
-
-## Errors
-
-These codes come from the options above:
-
-| Code | Meaning |
-| -- | -- |
-| `invalid_request` | `onlyIfAbsent` was passed to the batch form. |
-| `bad_request` | `onlyIfAbsent` isn't `true` or `false`. |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access is below `write`. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, a key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
+A `Promise` that will resolve to `true` when the key-value pair has been created or the existing key's value has been updated.
 
 ## Examples
 
@@ -100,13 +70,6 @@ These codes come from the options above:
 </html>
 ```
 
-<strong class="example-title">Claim a name only if nobody has it yet</strong>
-
-```js
-const claimed = await puter.kv.set('room:lobby', { createdAt: Date.now() }, { onlyIfAbsent: true });
-puter.print(claimed ? 'Room created' : 'That room already exists');
-```
-
 <strong class="example-title">Create a new key-value pair</strong>
 
 ```html;kv-set

src/docs/src/KV/share.md

@@ -1,146 +0,0 @@
----
-title: puter.kv.share()
-description: Share the keys under a prefix with another Puter user, so they can watch, read, or change them.
-platforms: [websites, apps, nodejs, workers]
----
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-Shares the keys under a prefix with another Puter user. The other user becomes the share's holder, and you stay its owner. The keys stay in your store, and the holder reaches them through the share.
-
-Each share has a `handle`. The holder finds it with [`puter.kv.listShared()`](/KV/listShared/) and passes it as `handle` to the other [`puter.kv`](/KV/) methods. [Sharing with other users](/KV/#sharing-with-other-users) shows how a holder uses a share.
-
-## Syntax
-
-```js
-puter.kv.share(prefix, recipient)
-puter.kv.share(prefix, recipient, access)
-puter.kv.share(options)
-```
-
-## Parameters
-
-#### `prefix` (String) (required)
-
-The key prefix to share, such as `'list:42:'`. The share covers every key that starts with it. The trailing `:` is optional, and the returned `prefix` always ends with one.
-
-A share stays on the prefix it was made for. Build the prefix from an id that never changes, such as `list:<uuid>:`, rather than from a name.
-
-The segments between the `:` separators can use only lowercase letters (`a`-`z`), digits, `_`, `.`, and `-`, as in `list:42:` or `room_1.draft-a:`. A prefix can't be empty or have an empty segment such as `list::42:`. A prefix with other characters, such as `List:42:` or `café:`, or with an empty segment is rejected with `invalid_kv_share_prefix`.
-
-The longest prefix depends on the app's uid and the access level. For an app uid of the usual form, `app-` and a uuid, the prefix without its trailing `:` can be at most 168 characters for `'watch'`, 163 for `'read'`, and 162 for `'write'`. In the store that belongs to no app, it can be at most 199, 194, and 193. A longer prefix is rejected with `invalid_kv_share_prefix`, and the error message gives the limit.
-
-A new share is also rejected with `invalid_kv_share_prefix` when its prefix differs from one of your existing shares with the same user only in letter case.
-
-#### `recipient` (String | Object) (required)
-
-The user to share with, as a username, `{ username }`, or `{ uid }` with the user's uuid. A string that contains `@` is rejected with `invalid_recipient`.
-
-#### `access` (String) (optional)
-
-What the holder can do. Defaults to `'read'`. Each level includes the ones before it.
-
-- `'watch'`: receive [events](/Events/subjects/#sharing-key-value-data-with-another-user) when keys under the prefix change.
-- `'read'`: also read keys with [`puter.kv.get()`](/KV/get/) and [`puter.kv.list()`](/KV/list/).
-- `'write'`: also change and delete keys with every other [`puter.kv`](/KV/) method, such as [`puter.kv.set()`](/KV/set/), [`puter.kv.incr()`](/KV/incr/) and [`puter.kv.del()`](/KV/del/). Write access includes delete, so a holder can change or remove any key under the prefix.
-
-#### `options` (Object)
-
-The options form takes these properties:
-
-- `prefix` (String) (required): The key prefix, as above.
-- `recipient` (String | Object) (required): Who to share with, as above.
-- `access` (String): What the holder can do, as above. Defaults to `'read'`.
-- `label` (String | null): Plain text the holder is shown with the share, such as `'Groceries from Dan'`. Whitespace at either end is trimmed, and the rest can be at most 128 characters and 512 bytes of UTF-8. Control characters, invisible formatting characters (such as zero-width spaces and text direction marks), line breaks, and more than 3 combining marks on one character are rejected with `kv_share_label_invalid`. An empty string means no label.
-- `appUuid` (String): The app whose data to share. Outside an app, such as in a Node.js script using the user's auth token, it can name any app that exists. An app always shares its own data, and passing a different app's id fails with `events_kv_handle_outside_namespace`.
-
-Without an app, [`puter.kv`](/KV/) uses a store that belongs to no app. Shares of that store have an `appUid` of `null`.
-
-## Return value
-
-A `Promise` that resolves to the share:
-
-- `handle` (String): The share's id. The holder passes it as `handle`.
-- `prefix` (String): The shared prefix, ending with `:`.
-- `access` (String): `'watch'`, `'read'`, or `'write'`.
-- `appUid` (String | null): The app whose data is shared, or `null` for the store that belongs to no app.
-- `holder` (String): The holder's username.
-- `label` (String | null): The label the holder is shown.
-- `createdAt` (Number): When the share was made, in Unix seconds.
-
-## Sharing the same prefix again
-
-Sharing the same prefix of the same app's data with the same user again changes the existing share instead of making a second one. The share keeps its `handle` and `createdAt` and gets the new `access`. Use this to raise or lower a holder's access. The holder's subscriptions through the handle keep working.
-
-Leave out `label` to keep the current label, pass a new one to replace it, or pass `null` to clear it.
-
-## What the holder sees
-
-The holder is never told who shared or what the prefix is. The keys they read and write are relative to the prefix. The label is the only thing about the share you choose to tell them.
-
-When the share is of an app's data, the holder gets a `kv.share.received` [notification](/Events/subjects/#notifications) inside that app. It isn't sent when you change an existing share, and isn't sent for shares of the store that belongs to no app. The holder gets at most 5 of these an hour from the same owner. A share past that is still made, without a notification. The live notification needs notifications to be turned on for events on the deployment, so have the holder's app call [`puter.kv.listShared()`](/KV/listShared/) when it opens. See [Sharing with other users](/KV/#sharing-with-other-users).
-
-## Who can share
-
-- **Account.** Where the deployment requires a confirmed email address, an unconfirmed account is rejected with `account_is_not_verified`. Sharing doesn't need a phone number, a card, or a paid plan. A temporary account can't share and gets `events_kv_handle_requires_account`.
-- **Apps.** An app can share only its own data, and only with the user's consent, which it asks for with [`puter.perms.request('kvShare', …)`](/Perms/request/). The consent names a prefix and a level. It covers that prefix and every key under it, at that level and the levels below it.
-- **Recipient blocks.** A user who blocked you, or who doesn't accept shares from anyone, can't be shared with. The call fails with `recipient_not_accepting_shares`. A block added later doesn't remove an existing share. You can still lower its access, clear its label with `label: null`, or stop it, and raising its access or setting a new label fails with `recipient_not_accepting_shares`.
-
-See [Rate Limits and Quotas](/rate-limits-and-quotas/#events) for how many shares an account can make per minute and hold at once.
-
-## Errors
-
-The promise rejects with `{ message, code }`:
-
-| Code | Meaning |
-| -- | -- |
-| `invalid_recipient` | `recipient` contains `@`, or isn't a username, `{ username }`, or `{ uid }`. |
-| `subject_does_not_exist` | No user has that username or uuid. |
-| `bad_request` | You named yourself as the recipient, or `appUuid` isn't the id of an app that exists. |
-| `invalid_kv_share_prefix` | `prefix` is empty, too long, has an empty segment, or has a character other than lowercase letters, digits, `_`, `.`, and `-` between its separators, or differs from one of your shares with the same user only in letter case. |
-| `kv_share_access_invalid` | `access` isn't `'watch'`, `'read'`, or `'write'`. |
-| `kv_share_label_invalid` | `label` isn't a string or `null`, is too long, or contains a character it can't have. |
-| `recipient_not_accepting_shares` | The recipient blocked you, or doesn't accept shares. On an existing share, you raised its access or set a new label. |
-| `account_is_not_verified` | Your email address isn't confirmed. |
-| `events_kv_handle_requires_account` | A temporary account tried to share. |
-| `events_kv_handle_limit_reached` | You already hold as many live shares as your plan allows. |
-| `events_kv_handle_not_delegated` | An app shared without the user's consent for that prefix and level. |
-| `events_kv_handle_outside_namespace` | An app named another app's data. |
-| `events_kv_handle_owner_only` | The call came from an access token with less access than the account. |
-| `forbidden` | An app shared through an access token it issued. |
-| `kv_handles_disabled` | `read` and `write` shares are turned off on this deployment. |
-| `events_kv_handles_disabled` | `watch` shares are turned off on this deployment. |
-| `events_disabled` | Events, which `watch` shares need, are turned off on this deployment. |
-| `too_many_requests` | Over the rate limit, or another change to the same share was still running. Try again. |
-
-## Examples
-
-<strong class="example-title">Share a list with another user</strong>
-
-```js
-const prefix = `list:${crypto.randomUUID()}:`;
-await puter.kv.set(`${prefix}meta`, { title: 'Groceries' });
-
-const share = await puter.kv.share(prefix, 'alice', 'write');
-puter.print(`Shared with ${share.holder} as ${share.access}`);
-```
-
-<strong class="example-title">Add a label, and lower the access later</strong>
-
-```js
-const share = await puter.kv.share({
-    prefix: 'trip:japan-2027:',
-    recipient: 'alice',
-    access: 'write',
-    label: 'Japan 2027',
-});
-
-// Same prefix and user, so this changes the same share.
-await puter.kv.share('trip:japan-2027:', 'alice', 'read');
-```
-
-## Related
-
-- [`puter.kv.unshare()`](/KV/unshare/) - Stop a share
-- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
-- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you

src/docs/src/KV/unshare.md

@@ -1,82 +0,0 @@
----
-title: puter.kv.unshare()
-description: Stop sharing key-value data with another user, or remove your own access to data shared with you.
-platforms: [websites, apps, nodejs, workers]
----
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-Stops a share made with [`puter.kv.share()`](/KV/share/). Either side can call it:
-
-- **The owner** revokes the share. The holder loses access, and any narrower share you made with the same holder inside the same prefix stops too.
-- **The holder** removes their own access. Any narrower share they hold from the same owner inside the same prefix stops too.
-
-The handle stops working right away for every [`puter.kv`](/KV/) call, and persistent subscriptions on it are suspended with `permission_revoked`. If a wider share the holder still has covers the same keys, calls through the stopped handle can keep working for up to 60 seconds. A stopped share stays in the owner's [`listSharedByMe()`](/KV/listSharedByMe/) listing with `revokedAt` and `revokedBy` set. The keys themselves stay in the owner's store.
-
-## Syntax
-
-```js
-puter.kv.unshare(handle)
-```
-
-## Parameters
-
-#### `handle` (String) (required)
-
-The share's `handle`, from [`puter.kv.share()`](/KV/share/), [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/), or [`puter.kv.listShared()`](/KV/listShared/).
-
-## Return value
-
-A `Promise` that resolves to:
-
-- `handle` (String): The share that stopped.
-- `revokedAt` (Number): When it stopped, in Unix seconds.
-
-Stopping a share that already stopped resolves the same way again.
-
-## Who can unshare
-
-- An app can stop only shares of its own data. To revoke as the owner, it also needs the user's consent for the prefix, the same consent [`puter.kv.share()`](/KV/share/) needs. To remove the user's own access as the holder, it needs no consent.
-- A handle that isn't yours, as owner or holder, is rejected with `subject_does_not_exist`, the same as one that doesn't exist.
-
-Unsharing works when sharing is turned off on the deployment, so you can always stop a share.
-
-## Errors
-
-The promise rejects with `{ message, code }`:
-
-| Code | Meaning |
-| -- | -- |
-| `invalid_request` | No `handle` was given. |
-| `subject_does_not_exist` | The handle doesn't exist, or you're neither its owner nor its holder. |
-| `events_kv_handle_not_delegated` | An app stopped its user's share after the user withdrew its consent. |
-| `events_kv_handle_owner_only` | The owner's call came from an access token with less access than the account, or from an app whose data the share isn't. |
-| `too_many_requests` | Over the rate limit, which sharing and unsharing count toward together. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events). |
-
-## Examples
-
-<strong class="example-title">Revoke a share you made</strong>
-
-```js
-const share = await puter.kv.share('list:42:', 'alice', 'write');
-
-const { revokedAt } = await puter.kv.unshare(share.handle);
-puter.print(`Stopped at ${new Date(revokedAt * 1000).toISOString()}`);
-```
-
-<strong class="example-title">Remove your own access to a share</strong>
-
-```js
-const { items } = await puter.kv.listShared();
-for (const share of items) {
-    if (share.label === 'Old project') {
-        await puter.kv.unshare(share.handle);
-    }
-}
-```
-
-## Related
-
-- [`puter.kv.share()`](/KV/share/) - Share keys with another user
-- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
-- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you

src/docs/src/KV/update.md

@@ -11,7 +11,6 @@ Update one or more paths within the value stored at a key. You can update nested
 ```js
 puter.kv.update(key, pathAndValueMap)
 puter.kv.update(key, pathAndValueMap, ttl)
-puter.kv.update(key, pathAndValueMap, ttl, optConfig)
 puter.kv.update({ key, pathAndValueMap, ttl })
 ```
 
@@ -33,15 +32,6 @@ Time-to-live in seconds. Omit it, or pass an empty string or `false`, to keep th
 
 Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `some.path[1].to.value`), and quoted property names (`["key.with.dots"]`). An empty path (`""`) targets the whole stored value. Use non-negative integer indexes in brackets to address arrays. When a path continues through an array element (for example, `[0].score`), that element must already exist. Missing object parents are created automatically; sparse array elements are not created. A path may chain at most 31 levels; a deeper one rejects with `bad_request`. Quoted names can't be empty. All of a call's paths go into one write, so a call fits at most 1,500 path segments and, with short field names, about 140 paths; split larger changes across calls. See [Rate Limits and Quotas](/rate-limits-and-quotas/).
 
-#### `optConfig` (Object) (optional)
-
-<div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>
-
-The last argument. It takes these properties:
-
-- `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
-- `appUuid` (String): Work on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.
-
 ## Return value
 
 Returns a `Promise` that resolves to the updated value stored at `key`.
@@ -64,11 +54,6 @@ A rejection carries an `Error` with a stable `code`:
 | `subject_does_not_exist` | `optConfig.appUuid` names an app that doesn't exist. |
 | `response_timeout` | Too many writers on the key right now — retry. |
 | `too_many_requests` | The rate limit was exceeded. See [Rate Limits and Quotas](/rate-limits-and-quotas/). |
-| `kv_handle_not_found` | `handle` doesn't exist, the share stopped, or it isn't shared with you. |
-| `kv_handle_access_denied` | The share's access doesn't allow this method. |
-| `kv_handle_option_invalid` | `handle` was combined with `appUuid` or `disableSharing`. |
-| `kv_handle_key_invalid` | With `handle`, the key is empty or longer than 768 bytes. |
-| `kv_handles_disabled` | Shares can't be used this way on this deployment. |
 
 ## Examples
 

src/docs/src/Perms.md

@@ -4,25 +4,17 @@ description: Request permissions to access user data and resources with Puter.js
 platforms: [websites, apps]
 ---
 
-The Permissions API enables your application to request access to user data and resources such as email addresses, files and folders, apps, subdomains, and other apps' saved data.
+The Permissions API enables your application to request access to user data and resources such as email addresses, special folders (Desktop, Documents, Pictures, Videos), apps, subdomains, and other apps' saved data.
 
 Each request names a resource and the details that resource needs:
 
 ```js
 await puter.perms.request('email');
-await puter.perms.request('fs', { path: '~/Documents/notes.txt', access: 'write' });
 await puter.perms.request('folder', { name: 'Documents', access: 'write' });
 await puter.perms.request('apps', { access: 'read' });
 await puter.perms.request('appData', { app: 'contacts', scopes: 'read' });
 ```
 
-The accepted values are also constants on `puter.perms.Resource`, `puter.perms.Access`, and `puter.perms.Folder`:
-
-```js
-const { Resource, Access } = puter.perms;
-await puter.perms.request(Resource.FS, { path: '~/Documents', access: Access.READ });
-```
-
 ## Features
 
 <div style="overflow:hidden; margin-bottom: 30px;">

src/docs/src/Perms/check.md

@@ -20,15 +20,13 @@ puter.perms.check(requests)
 
 ## Parameters
 
-The same as [`puter.perms.request()`](/Perms/request/). The resource table there lists what each one accepts, and the same `puter.perms.Resource` and `puter.perms.Access` constants work here. The `create` field is validated the same way, but `check()` never creates anything. It only reports whether access is already held. Invalid details reject with `{ message, code: 'invalid_argument' }`, the same as `request()`.
-
-For `'fs'`, access to a folder counts for everything inside it, so a check for a file inside a folder the app can already read answers `true`.
+The same as [`puter.perms.request()`](/Perms/request/) — see the resource table there for what each one accepts. `create` is accepted and validated for signature symmetry, but `check()` never creates anything — it only ever reports whether access is already held. An invalid `create` value rejects with `{ message, code: 'invalid_argument' }`, the same as `request()`.
 
 ## Return value
 
 A `Promise` that resolves to `true` if the access is already granted, or `false` otherwise. The array form resolves to an array of booleans, in the order asked.
 
-Where a resource needs more than one permission, such as `'appData'` with several scopes, the answer is `true` only when the whole set is granted. A partly-granted set answers `false`, since a prompt is still needed.
+Where a resource needs more than one permission — `'appData'` with several scopes, or `'permission'` with a list — the answer is `true` only when the whole set is granted. A partly-granted set answers `false`, since a prompt is still needed.
 
 The promise rejects if the check itself cannot be made (for example when the caller isn't signed in). A failure is not reported as `false`: an app that couldn't tell the two apart would prompt someone who had already granted it.