@substrat-run/adapter-cloudflare 0.39.0 → 0.41.0

package/dist/host.js

@@ -1,7 +1,8 @@
-import { accessLogEntry, adminLogEntry, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, connectionGrant, connectionSecret, systemGrant, entitlementGrant, entitlementGrantInput, subjectRef, createConnectionInput, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, platformRequest, } from '@substrat-run/contracts';
+import { accessLogEntry, adminLogEntry, attachmentRecord, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, connectionGrant, connectionSecret, systemGrant, entitlementGrant, entitlementGrantInput, subjectRef, createConnectionInput, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, platformRequest, } from '@substrat-run/contracts';
 import { normalizeHostname, toRouteTarget } from './route-resolver.js';
-import { resolveScopeRecord, ulid, backoffAt, resolveRetryPolicy, unconfiguredSecretBox, } from '@substrat-run/kernel';
+import { attachmentBlobKey, resolveScopeRecord, ulid, backoffAt, resolveRetryPolicy, unconfiguredSecretBox, } from '@substrat-run/kernel';
 import { tenantStoreDatabaseName } from './d1.js';
+import { blobStoreBucketName, r2TenantBlobStore } from './r2.js';
 /** DO row → contract shape. Never reads the secrets table — that is the split. */
 const toConnection = (r) => connection.parse({
     id: r.id,
@@ -69,6 +70,8 @@ export class CloudflareScopeHost {
     admin;
     scopeNs;
     cp;
+    /** No control plane bound — `this.cp` is the throwing null object (Phase 3, CP-less). */
+    cpLess;
     /** Project + evaluate permissions scope-locally (scope-local-permissions.md). */
     scopeLocalPermissions;
     // Registration-mechanics bookkeeping (validation only — the DO executes).
@@ -85,6 +88,10 @@ export class CloudflareScopeHost {
     fetchImpl;
     /** The live D1 client for per-tenant stores (#301); undefined ⇒ refuse loudly. */
     tenantStores;
+    /** The live R2 client for per-tenant blob stores (#473); undefined ⇒ refuse loudly. */
+    blobStores;
+    /** Worker-side attachment-bucket resolver (#473); undefined ⇒ attachments() refuses. */
+    attachmentBuckets;
     executors = new Map();
     /**
      * The event currently being effected, stamped onto admin rows the executor writes.
@@ -109,9 +116,12 @@ export class CloudflareScopeHost {
     constructor(options) {
         this.secretBox = options.secretBox ?? unconfiguredSecretBox;
         this.tenantStores = options.tenantStores;
+        this.blobStores = options.blobStores;
+        this.attachmentBuckets = options.attachmentBuckets;
         this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
         this.scopeLocalPermissions = options.scopeLocalPermissions ?? false;
         this.scopeNs = options.scope;
+        this.cpLess = !options.controlPlane;
         this.cp = options.controlPlane
             ? options.controlPlane.get(options.controlPlane.idFromName('control-plane'))
             : nullControlPlane();
@@ -576,6 +586,119 @@ export class CloudflareScopeHost {
         }
         return this.tenantStores;
     }
+    async provisionBlobStore(actor, input) {
+        // Mirror of provisionTenantStore (#301) with R2 in place of D1: fail-closed tenant
+        // gate, ledger idempotency, deterministic name so a crashed retry converges, DO
+        // first-writer-wins with loser teardown.
+        const r2 = this.requireBlobStores(`provisionBlobStore(tenant=${input.tenantId} vertical=${input.vertical} binding=${input.binding})`);
+        const tenant = await this.cp.getTenant(input.tenantId);
+        if (!tenant) {
+            throw new Error(`cannot provision blob store under unknown tenant: ${input.tenantId}`);
+        }
+        if (tenant.status !== 'active') {
+            throw new Error(`cannot provision blob store under non-active tenant (status: ${tenant.status}): ${input.tenantId}`);
+        }
+        const existing = await this.cp.getBlobStore(input.tenantId, input.vertical, input.binding);
+        if (existing)
+            return { binding: input.binding, kind: 'blob', ref: existing.ref };
+        const name = await blobStoreBucketName(input.tenantId, input.vertical, input.binding);
+        const ref = await r2.create(name);
+        const stored = await this.cp.putBlobStore({
+            tenantId: input.tenantId,
+            vertical: input.vertical,
+            binding: input.binding,
+            kind: 'blob',
+            ref,
+            createdAt: new Date().toISOString(),
+        });
+        if (stored.ref !== ref) {
+            await r2.remove(ref).catch(() => undefined);
+            return { binding: input.binding, kind: 'blob', ref: stored.ref };
+        }
+        await this.recordAdmin(actor, 'provisionBlobStore', { tenantId: input.tenantId, vertical: input.vertical }, null, { binding: input.binding, kind: 'blob', ref });
+        return { binding: input.binding, kind: 'blob', ref };
+    }
+    /** The injected R2 client, or a loud refusal naming what to configure. */
+    requireBlobStores(what) {
+        if (!this.blobStores) {
+            throw new Error(`per-tenant blob stores are not configured on this host (#473): pass ` +
+                `CloudflareScopeHostOptions.blobStores (createR2BlobStores with the platform's ` +
+                `Cloudflare credential) — refused ${what}`);
+        }
+        return this.blobStores;
+    }
+    async attachments(principal, tenantId, scopeId) {
+        // Same fail-closed lifecycle gate + lazy-migration as getScope (#473). The permission
+        // gates and metadata facts live in the ScopeDO (per-scope serialization, spine event
+        // in the same transaction); bytes go straight to the per-tenant R2 bucket through the
+        // binding the vertical's worker resolved — never through the DO.
+        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.migrateAndRecord(scopeId);
+        if (!this.attachmentBuckets) {
+            throw new Error(`attachments are not configured on this host (#473): pass ` +
+                `CloudflareScopeHostOptions.attachmentBuckets — (tenantId) => ` +
+                `env[blobStoreBindingName('<BINDING>', tenantId)] for the vertical's declared blob store`);
+        }
+        const bucket = await this.attachmentBuckets(tenantId);
+        if (!bucket) {
+            throw new Error(`no attachment bucket resolved for tenant ${tenantId} (#473) — is the per-tenant blob ` +
+                `store provisioned and its r2_bucket binding attached to the serving script?`);
+        }
+        const store = r2TenantBlobStore(bucket);
+        const stub = this.scopeStub(scopeId);
+        const sha256Hex = async (body) => {
+            const digest = await crypto.subtle.digest('SHA-256', body);
+            return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+        };
+        return {
+            upload: async (input) => {
+                const id = ulid();
+                const key = attachmentBlobKey(scopeId, id);
+                const record = attachmentRecord.parse({
+                    id,
+                    entity: input.entity,
+                    filename: input.filename,
+                    contentType: input.contentType,
+                    size: input.body.byteLength,
+                    sha256: await sha256Hex(input.body),
+                    visibility: input.visibility,
+                    createdBy: principal,
+                    createdAt: new Date().toISOString(),
+                });
+                // Bytes first, row second — a crash between the two leaves an orphaned object
+                // (harmless, GC-able), never a row without bytes; a refused gate compensates.
+                await store.put(key, input.body, { contentType: input.contentType });
+                try {
+                    return await stub.attachmentAdd(record, principal, tenantId, scopeId);
+                }
+                catch (err) {
+                    await store.delete(key).catch(() => { });
+                    throw err;
+                }
+            },
+            list: (entity) => stub.attachmentList(entity, principal, tenantId, scopeId),
+            open: async (attachmentId) => {
+                const record = await stub.attachmentAuthorize(attachmentId, 'read', principal, tenantId, scopeId);
+                if (!record)
+                    return null;
+                const obj = await store.get(attachmentBlobKey(scopeId, record.id));
+                if (!obj) {
+                    throw new Error(`attachment ${record.id}: bytes missing from the blob store — the metadata row ` +
+                        `survived something the object did not (rewind/reap); see the #473 integrity notes`);
+                }
+                if ((await sha256Hex(obj.body)) !== record.sha256) {
+                    throw new Error(`attachment ${record.id}: bytes do not match the recorded sha256`);
+                }
+                return { record, body: obj.body, contentType: obj.contentType ?? record.contentType };
+            },
+            remove: async (attachmentId) => {
+                const removed = await stub.attachmentRemove(attachmentId, principal, tenantId, scopeId);
+                if (removed)
+                    await store.delete(attachmentBlobKey(scopeId, removed.id)).catch(() => { });
+                return removed;
+            },
+        };
+    }
     async importScope(actor, input, dump) {
         // Create the destination scope (directory row + DO + lazy migrate); the DO then
         // replaces its provisioned schema with the dump wholesale (drop-then-replay), so
@@ -678,12 +801,12 @@ export class CloudflareScopeHost {
             throw err;
         }
     }
-    async getScope(principal, tenantId, scopeId) {
+    async getScope(principal, tenantId, scopeId, options) {
         // Lifecycle gates (control-plane.md §4.1/§4.2), the K-3 fail-closed path,
         // evaluated durably in the ControlPlaneDO. A throw propagates here.
         await this.cp.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
-        return this.buildStub(tenantId, scopeId, principal);
+        return this.buildStub(tenantId, scopeId, principal, undefined, undefined, options);
     }
     /**
      * A scope stub whose authority is a CONNECTION (#97).
@@ -741,10 +864,15 @@ export class CloudflareScopeHost {
         if (!schedules || schedules.length === 0)
             return report;
         // Only run on a live scope of this tenant; a scope archived between the sweep's
-        // enumeration and here simply has nothing due.
-        const rec = await this.cp.getScopeRecord(tenantId, scopeId);
-        if (!rec || rec.status !== 'active')
-            return report;
+        // enumeration and here simply has nothing due. A CP-less host has no directory
+        // to ask (#461) — it already trusts the router-asserted (tenant, scope) for the
+        // whole request path, and lifecycle for its scopes lives wherever provisioning
+        // does, so the grant check below is the only gate it can and does enforce.
+        if (!this.cpLess) {
+            const rec = await this.cp.getScopeRecord(tenantId, scopeId);
+            if (!rec || rec.status !== 'active')
+                return report;
+        }
         const stub = this.scopeStub(scopeId);
         // The grant IS the switch (#383): run only where the scope holds a live
         // `system:<moduleId>` grant. Skips a foreign-vertical scope and a per-tenant
@@ -779,7 +907,7 @@ export class CloudflareScopeHost {
         return report;
     }
     /** The stub body, shared by the principal, connection, and system doors. */
-    buildStub(tenantId, scopeId, principal, connectionId, systemModuleId) {
+    buildStub(tenantId, scopeId, principal, connectionId, systemModuleId, options) {
         const stub = this.scopeStub(scopeId);
         const cp = this.cp;
         const operationEntitlement = this.operationEntitlement;
@@ -802,9 +930,13 @@ export class CloudflareScopeHost {
                 if (requiredKey && !(await cp.tenantHoldsEntitlement(tenantId, requiredKey))) {
                     return Promise.reject(new Error(`operation not entitled: ${operation} — tenant does not hold '${requiredKey}'`));
                 }
-                const result = (await stub.invoke(operation, input, asPrincipalId, tenantId, scopeId, connectionId, requiredKey, systemModuleId));
+                const envelope = await stub.invoke(operation, input, asPrincipalId, tenantId, scopeId, connectionId, requiredKey, systemModuleId);
                 await this.drainExecutors(tenantId, scopeId);
-                return result;
+                // #458: the operation committed having enqueued platform intents — tell the
+                // caller's harness so it can flag the response for the router kick (#381).
+                if (envelope.platformRequests > 0)
+                    options?.onPlatformRequests?.(envelope.platformRequests);
+                return envelope.result;
             },
         };
     }
@@ -933,7 +1065,13 @@ export class CloudflareScopeHost {
                 await this.fanOut(tenantId); // role definitions are projected into the tenant's scopes
             },
             listRoles: async (actor, filter) => {
-                const rows = await this.cp.listRoles({ tenantId: filter?.tenantId, source: filter?.source });
+                const rows = await this.cp.listRoles({
+                    tenantId: filter?.tenantId,
+                    source: filter?.source,
+                    limit: filter?.limit,
+                    cursor: filter?.cursor,
+                    order: filter?.order,
+                });
                 await this.recordAccess(actor, 'listRoles', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
                 // Parsed, not cast — the same parse the pure adapter does, which is what
                 // makes the shared contract suite mean anything.
@@ -1110,6 +1248,9 @@ export class CloudflareScopeHost {
                     tenantId: filter?.tenantId,
                     scopeId: filter?.scopeId,
                     status: filter?.status,
+                    limit: filter?.limit,
+                    cursor: filter?.cursor,
+                    order: filter?.order,
                 });
                 await this.recordAccess(actor, 'listHostnames', { tenantId: filter?.tenantId ?? null, scopeId: filter?.scopeId ?? null }, filter, rows.length);
                 return rows.map(mapHostname);
@@ -1161,9 +1302,9 @@ export class CloudflareScopeHost {
                 await this.cp.insertVertical(parsed.slug, parsed.name, parsed.source, parsed.ownerTenant, envSpecJson, installSpecJson, parsed.listed ? 1 : 0, new Date().toISOString());
                 await this.recordAdmin(actor, 'registerVertical', { tenantId: null }, null, parsed);
             },
-            listVerticals: async (actor) => {
-                const rows = await this.cp.listVerticals();
-                await this.recordAccess(actor, 'listVerticals', {}, null, rows.length);
+            listVerticals: async (actor, page) => {
+                const rows = await this.cp.listVerticals(page);
+                await this.recordAccess(actor, 'listVerticals', {}, page ?? null, rows.length);
                 return rows.map(mapVertical);
             },
             publishVersion: async (actor, input) => {
@@ -1192,8 +1333,8 @@ export class CloudflareScopeHost {
                     admission: selfAdmits ? 'admitted' : 'pending',
                 });
             },
-            listVersions: async (actor, verticalSlug) => {
-                const rows = await this.cp.listVersions(verticalSlug);
+            listVersions: async (actor, verticalSlug, page) => {
+                const rows = await this.cp.listVersions(verticalSlug, page);
                 await this.recordAccess(actor, 'listVersions', {}, { verticalSlug }, rows.length);
                 return rows.map(mapVersion);
             },
@@ -1240,12 +1381,18 @@ export class CloudflareScopeHost {
                 const existing = await this.cp.readVertical(slug);
                 if (!existing)
                     throw new Error(`unknown vertical '${slug}'`);
-                // Refuse while any scope is bound: a deleted registry row would strand those
-                // scopes' version pins and routing. Deployed dispatch scripts are NOT reaped
-                // here — they become orphans for the cleanup script (#248).
+                // Refuse while any restorable scope is bound: a deleted registry row would strand
+                // those scopes' version pins and routing. An `archived` scope (a deleted app) still
+                // blocks — unarchive can bring it back — but the refusal names reap/restore, not
+                // "delete", because the app itself is already gone. `reaped` is terminal history and
+                // never blocks. Deployed dispatch scripts are NOT reaped here — they become orphans
+                // for the cleanup script (#248).
                 const bound = await this.cp.countScopesForVertical(slug);
-                if (bound > 0) {
-                    throw new Error(`vertical '${slug}' still backs ${bound} scope(s) — delete or rebind them first`);
+                if (bound.live > 0) {
+                    throw new Error(`vertical '${slug}' still backs ${bound.live} scope(s) — delete or rebind them first`);
+                }
+                if (bound.archived > 0) {
+                    throw new Error(`vertical '${slug}' still backs ${bound.archived} archived scope(s) — reap or restore them first`);
                 }
                 await this.cp.deleteVertical(slug);
                 await this.recordAdmin(actor, 'deleteVertical', { tenantId: null }, { slug, source: existing.source, ownerTenant: existing.owner_tenant }, null);
@@ -1355,8 +1502,8 @@ export class CloudflareScopeHost {
                 }
                 await this.recordAdmin(actor, 'promoteVersion', { tenantId: null, vertical: verticalSlug }, outgoing ? { versionId: outgoing.id, version: outgoing.version } : null, { channel, versionId, version: incoming.version, acknowledged: ack });
             },
-            listChannels: async (actor, verticalSlug) => {
-                const rows = await this.cp.listChannels(verticalSlug);
+            listChannels: async (actor, verticalSlug, page) => {
+                const rows = await this.cp.listChannels(verticalSlug, page);
                 // The serving script runs ONE version (#286); surface it on the prod row so a
                 // failed in-place serve (channel moved, serve did not) reads honestly instead of
                 // claiming the new version is live (#321).
@@ -1370,8 +1517,8 @@ export class CloudflareScopeHost {
                     servingVersionId: r.channel === 'prod' ? serving : null,
                 }));
             },
-            listChannelHistory: async (actor, verticalSlug, channel) => {
-                const rows = await this.cp.listChannelHistory(verticalSlug, channel);
+            listChannelHistory: async (actor, verticalSlug, channel, page) => {
+                const rows = await this.cp.listChannelHistory(verticalSlug, channel, page);
                 await this.recordAccess(actor, 'listChannelHistory', {}, { verticalSlug, channel }, rows.length);
                 return rows.map((r) => channelHistoryEntry.parse({
                     id: r.id,
@@ -1547,10 +1694,10 @@ export class CloudflareScopeHost {
                 const before = await this.cp.reapTenant(tenantId);
                 await this.recordAdmin(actor, 'reapTenant', { tenantId }, { status: before }, { status: 'reaped' });
             },
-            listTenants: async (actor) => {
-                const tenants = (await this.cp.listTenants()).map((t) => tenantSchema.parse(t));
+            listTenants: async (actor, page) => {
+                const tenants = (await this.cp.listTenants(page)).map((t) => tenantSchema.parse(t));
                 // Enumerating every tenant on the platform is the read this log exists for.
-                await this.recordAccess(actor, 'listTenants', {}, null, tenants.length);
+                await this.recordAccess(actor, 'listTenants', {}, page ?? null, tenants.length);
                 return tenants;
             },
             getTenant: async (actor, tenantId) => {
@@ -1567,6 +1714,9 @@ export class CloudflareScopeHost {
                             : [filter.status]
                         : undefined,
                     vertical: filter?.vertical,
+                    limit: filter?.limit,
+                    cursor: filter?.cursor,
+                    order: filter?.order,
                 });
                 await this.recordAccess(actor, 'listScopes', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
                 return rows.map(mapScope);
@@ -1591,6 +1741,21 @@ export class CloudflareScopeHost {
                     createdAt: r.created_at,
                 }));
             },
+            listBlobStores: async (actor, filter) => {
+                const rows = await this.cp.listBlobStores({
+                    tenantId: filter?.tenantId,
+                    vertical: filter?.vertical,
+                });
+                await this.recordAccess(actor, 'listBlobStores', { tenantId: filter?.tenantId ?? null }, filter ?? null, rows.length);
+                return rows.map((r) => ({
+                    tenantId: r.tenant_id,
+                    vertical: r.vertical,
+                    binding: r.binding,
+                    kind: 'blob',
+                    ref: r.ref,
+                    createdAt: r.created_at,
+                }));
+            },
             listScopeTables: async (actor, tenantId, scopeId) => {
                 // K-3 cross-check on the shared directory BEFORE reaching the scope DO: a pair
                 // that does not resolve is unreachable, never another tenant's database.
@@ -1812,8 +1977,8 @@ export class CloudflareScopeHost {
                     return; // idempotent, and a no-op is not audited
                 await this.recordAdmin(actor, 'revokeConnection', { tenantId: row.tenant_id, vertical: row.vertical }, { status: row.status }, { id, provider: row.provider, status: 'revoked', revokedAt: now });
             },
-            openConnection: async (tenantId, vertical, provider) => {
-                const row = await this.cp.readLiveConnection(tenantId, vertical, provider);
+            openConnection: async (tenantId, vertical, provider, externalAccountRef) => {
+                const row = await this.cp.readLiveConnection(tenantId, vertical, provider, externalAccountRef);
                 if (!row)
                     return undefined;
                 const secret = connectionSecret.parse(JSON.parse(await this.secretBox.open({ keyId: row.key_id, ciphertext: row.ciphertext })));
@@ -1889,6 +2054,8 @@ export class CloudflareScopeHost {
                     tenantId: filter?.tenantId,
                     method: filter?.method,
                     limit: filter?.limit,
+                    cursor: filter?.cursor,
+                    order: filter?.order,
                 });
                 // Reading the access log is itself a read. Recorded before returning, so
                 // the row describing this call is not in its own result.
@@ -2069,6 +2236,22 @@ export class CloudflareScopeHost {
                 object: `scope:${input.scopeId}`,
                 expires_at: null,
             },
+            // #461: each registered module's SCHEDULE grants (#383) ride the same unit —
+            // the CP-less mirror of `provisionScope`'s writeTuple loop. Without them the
+            // grant-is-the-switch check makes every schedule a silent no-op (`fired: 0`,
+            // no error — the #49 unfalsifiable zero).
+            ...[...this.moduleSchedules].flatMap(([modId, schedules]) => {
+                const perms = new Set();
+                for (const s of schedules)
+                    for (const p of s.permissions)
+                        perms.add(p);
+                return [...perms].map((perm) => ({
+                    subject: `system:${modId}`,
+                    relation: `granted:${perm}`,
+                    object: `scope:${input.scopeId}`,
+                    expires_at: null,
+                }));
+            }),
         ], 
         // #406: identity links, delivered by the platform with provisioning exactly as
         // entitlements are (#310). Preserve-on-undefined, so an absent field never wipes