@substrat-run/adapter-cloudflare 0.89.0 → 0.90.1

package/dist/host.js

@@ -1,6 +1,6 @@
 import { fromWireFailure, accessLogEntry, adminLogEntry, opsFailureEntry, attachmentRecord, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, entitlementGrant, entitlementGrantInput, instant, meterReading, subjectRef, createConnectionInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, subjectShredReceipt, platformRequest, connectorDispatchKind, outboundOfManifestJson, substratError, } from '@substrat-run/contracts';
 import { normalizeHostname, toRouteTarget } from './route-resolver.js';
-import { attachmentBlobKey, entitlementDenial, foldMeterReading, parseValidationRecords, resolveScopeRecord, ulid, backoffAt, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, openSealed, } from '@substrat-run/kernel';
+import { attachmentBlobKey, entitlementDenial, foldMeterReading, parseValidationRecords, resolveScopeRecord, ulid, backoffAt, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, openSealed, ImpersonationRefused, assertSessionUsable, impersonationRowValues, mapImpersonationRow, newImpersonationSession, } 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. */
@@ -28,6 +28,7 @@ function rowToPlatformRequest(r) {
         kind: r.kind,
         payload: JSON.parse(r.payload),
         requestedBy: JSON.parse(r.requested_by),
+        impersonation: r.impersonation == null ? null : JSON.parse(r.impersonation),
         status: r.status,
         attempts: r.attempts,
         lastError: r.last_error,
@@ -1025,6 +1026,33 @@ export class CloudflareScopeHost {
         await this.migrateAndRecord(scopeId);
         return this.buildStub(conn.tenant_id, scopeId, undefined, connectionId);
     }
+    /**
+     * Read a session and hold it to its own rules — the lookup behind both the door
+     * and every invoke through it. Kept in one place so the two can never disagree
+     * about what "still usable" means.
+     */
+    async resolveImpersonation(session, tenantId, scopeId) {
+        const row = await this.cp.readImpersonation(String(session));
+        if (!row)
+            throw new ImpersonationRefused(`unknown impersonation session: ${session}`);
+        const record = mapImpersonationRow(row);
+        assertSessionUsable(record, new Date().toISOString(), { tenantId, scopeId });
+        return record;
+    }
+    /**
+     * The impersonation door (K-42, #868) — mirror of `getConnectorScope` and
+     * `getSystemScope`. The session is the authority and it is read from the
+     * directory, never described by the caller: a stub can only be minted by naming
+     * a session somebody opened and the admin log already recorded.
+     */
+    async getImpersonatedScope(session, tenantId, scopeId, options) {
+        const record = await this.resolveImpersonation(session, tenantId, scopeId);
+        // The same lifecycle gate the principal door applies: a suspended tenant
+        // refuses a support session exactly as it refuses a user.
+        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.migrateAndRecord(scopeId);
+        return this.buildStub(tenantId, scopeId, record.principal, undefined, undefined, options, record.id);
+    }
     /**
      * A scope stub whose authority is a MODULE on a timer (#383) — the scheduler's
      * door, mirror of `getConnectorScope`. The module must be registered on this host
@@ -1095,8 +1123,16 @@ export class CloudflareScopeHost {
         }
         return report;
     }
-    /** The stub body, shared by the principal, connection, and system doors. */
-    buildStub(tenantId, scopeId, principal, connectionId, systemModuleId, options) {
+    /** The stub body, shared by the principal, connection, system and impersonation doors. */
+    buildStub(tenantId, scopeId, principal, connectionId, systemModuleId, options, 
+    /**
+     * K-42: the session this stub acts under. Re-read from the directory on
+     * EVERY invoke rather than captured here — a stub is a capability and
+     * nothing takes it away, so a session checked only at the door would be a
+     * time box that never runs out for the one caller holding it, and
+     * `endImpersonation` would stop nothing.
+     */
+    sessionId) {
         const stub = this.scopeStub(scopeId);
         const cp = this.cp;
         const operationEntitlement = this.operationEntitlement;
@@ -1125,7 +1161,9 @@ export class CloudflareScopeHost {
                         expired: r.expires_at !== null && r.expires_at <= now,
                     })))));
                 }
-                const envelope = await stub.invoke(operation, input, asPrincipalId, tenantId, scopeId, connectionId, requiredKey, systemModuleId, true, invokeOptions);
+                // K-42: resolved per invoke, so expiry and `endImpersonation` both bite.
+                const session = sessionId === undefined ? undefined : await this.resolveImpersonation(sessionId, tenantId, scopeId);
+                const envelope = await stub.invoke(operation, input, asPrincipalId, tenantId, scopeId, connectionId, requiredKey, systemModuleId, true, invokeOptions, session);
                 // The operation failed and the DO handed the error back as DATA — so it still
                 // has its code and extensions, which a throw across this boundary would have
                 // stripped down to a message (#113 §3). Rethrown here, where the caller expects
@@ -1154,7 +1192,24 @@ export class CloudflareScopeHost {
                     throw substratError('unavailable', `${operation} ran on a scope host that did not honour Idempotency-Key — the ` +
                         'operation may have executed a second time. Retry once the scope has been migrated');
                 }
-                const drained = await this.drainExecutors(tenantId, scopeId);
+                // K-42, and the same shape as the two skew refusals above with a sharper
+                // reason: a DO too old to know about sessions ran this as the impersonated
+                // principal with nothing stamped and no read-only bound. The write has
+                // committed; what this refuses is the SUCCESS, because a support session
+                // believed to be recorded and bounded is worse than no support session.
+                if (session !== undefined && envelope.impersonation?.honoured !== true) {
+                    throw substratError('unavailable', `${operation} ran on a scope host that did not understand impersonation — the ` +
+                        'operation may have run unrecorded and unbounded. Retry once the scope has ' +
+                        'been migrated');
+                }
+                // K-42, the coordinator half of the pure adapter's post-commit guard: a
+                // read-only session's transaction was rolled back, so it added nothing to
+                // this scope's outbox — and draining anyway would run executors and
+                // connectors as a side effect of a session that may not have side effects.
+                // Whatever the outbox already held is the drain sweep's own backstop.
+                const drained = session?.mode === 'read-only'
+                    ? { attempted: 0, delivered: 0, retrying: 0, deadLettered: 0, routedToPlatform: 0 }
+                    : await this.drainExecutors(tenantId, scopeId);
                 // #458: the operation committed having enqueued platform intents — tell the
                 // caller's harness so it can flag the response for the router kick (#381).
                 // Routed connector deliveries (#574 phase 3) count too: the inline drain just
@@ -2230,6 +2285,43 @@ export class CloudflareScopeHost {
                 await this.recordAccess(actor, 'shredSubject', { tenantId, scopeId }, { subjectId }, eventsRedacted);
                 return receipt;
             },
+            // -- impersonation (K-42, #868) ----------------------------------------
+            beginImpersonation: async (actor, input) => {
+                // Fail closed on the scope before minting anything: a session naming a
+                // scope that is not there is a credential for nothing, and issuing one
+                // anyway leaves the admin log recording an access that could not happen.
+                await this.assertScope(input.tenantId, input.scopeId);
+                const session = newImpersonationSession(ulid(), actor, input, new Date().toISOString());
+                await this.cp.writeImpersonation(impersonationRowValues(session));
+                // BEFORE the session is usable, so the log entry precedes every row it
+                // will ever touch. The reason rides in `after`: it is what a review reads
+                // first, and a log saying a session opened but not why is half a record.
+                await this.recordAdmin(actor, 'beginImpersonation', { tenantId: session.tenantId, scopeId: session.scopeId }, null, session);
+                return session;
+            },
+            endImpersonation: async (actor, id) => {
+                const row = await this.cp.readImpersonation(String(id));
+                if (!row)
+                    throw new ImpersonationRefused(`unknown impersonation session: ${id}`);
+                const before = mapImpersonationRow(row);
+                // Idempotent: "stop that session" must not fail because somebody else
+                // already stopped it.
+                if (before.endedAt !== null)
+                    return before;
+                await this.cp.endImpersonation(String(id), new Date().toISOString());
+                const after = mapImpersonationRow((await this.cp.readImpersonation(String(id))));
+                await this.recordAdmin(actor, 'endImpersonation', { tenantId: after.tenantId, scopeId: after.scopeId }, before, after);
+                return after;
+            },
+            listImpersonations: async (actor, filter) => {
+                const rows = await this.cp.listImpersonations(filter ?? {}, new Date().toISOString());
+                const sessions = rows.map(mapImpersonationRow);
+                // A staff READ, logged like every other one (K-24) — `result_count`
+                // included, which is what separates "checked one session" from
+                // "enumerated every support session on the platform".
+                await this.recordAccess(actor, 'listImpersonations', { tenantId: (filter?.tenantId ?? null) }, filter ?? null, sessions.length);
+                return sessions;
+            },
             grantEntitlement: async (actor, tenantId, entitlementKey, plan) => {
                 const input = entitlementGrantInput.parse(plan ?? {});
                 const result = await this.cp.grantEntitlement(tenantId, entitlementKey, input, actor);