@sekiban/dcb-runtime 0.2.0 → 0.2.2

package/README.md

@@ -5,9 +5,40 @@ Cloudflare Durable Object and HTTP runtime for Serialized DCB V1.
 This package is the matched-set runtime companion to `@sekiban/dcb-core`,
 `@sekiban/dcb-domain`, and `@sekiban/dcb-client`. Consumers such as the
 meeting-room Cloudflare sample import public entry points (`@sekiban/dcb-runtime`,
-`@sekiban/dcb-runtime/cloudflare`, `/d1`, `/d1-mv`, `/mv`, `/cosmos`) and re-export
+`@sekiban/dcb-runtime/cloudflare`, `/d1`, `/d1-mv`, `/mv`, and the experimental `/cosmos`) and re-export
 Durable Object classes from their Worker module graph as Cloudflare requires.
 
+The experimental Cosmos provider is never selected by environment values. A
+consumer must import `createCosmosStoreProvider` from `/cosmos` and pass it as
+`createRuntimeWorker({ storeProvider })`.
+
+## Query parameters
+
+A scalar query accepts only a parsed empty object. A list query accepts only
+`PageNumber`, `PageSize`, `NewestFirst`, and `consistency`. Any other parsed
+scalar value, and any unknown list key, is HTTP 400 `query_params_unsupported`
+with the message "The selected query does not support these parameters." The
+check runs after JSON parsing and endpoint matching and before projector
+lookup or a store read, on every backing. The V1 response envelope is
+unchanged. Typed query handlers are planned for `0.3.0`; their API is not
+defined here.
+
+## Configured bearer checks
+
+`checkConfiguredBearer(request, binding, options?)` is exported from
+`@sekiban/dcb-runtime` and `@sekiban/dcb-runtime/cloudflare`. `binding` is
+`unknown`. The result is `"unconfigured" | "missing" | "invalid" | "authorized"`.
+Callers choose the HTTP status. A binding is configured only when it is a
+string containing a non-whitespace character. The default normalization keeps
+the original bytes. `{ tokenNormalization: "trim" }` is the only other mode
+and is reserved for incident maintenance, which already trimmed its token.
+
+The helper hashes the complete expected `Bearer ` credential and the complete
+supplied `Authorization` header with global WebCrypto SHA-256, then compares
+every digest byte. It does not use Node crypto. Scheme spelling and case are
+exact. Treat `unconfigured` as disabled on every exposed shared-secret route.
+Do not compare a blank binding as if it were a credential.
+
 ## License
 
 Elastic License 2.0. See [LICENSE](./LICENSE).

package/dist/allocator/AllocatorDurableObject.js

@@ -10,6 +10,8 @@ const ATTEMPT_KEY_PREFIX = "attempt:";
 const ROLLBACK_WARNING_WINDOW_MS = 1000n;
 class AllocationTransactionFault extends Error {
 }
+class ImportSeedRequiredError extends Error {
+}
 function json(body, status = 200) {
     return new Response(JSON.stringify(body), {
         status,
@@ -55,7 +57,19 @@ function seedFrom(value) {
     catch {
         return { error: "highWatermark must be an allocator SUID" };
     }
-    return { value: { importId: value.importId, leaseEpoch: value.leaseEpoch, highWatermark: value.highWatermark } };
+    let storeMaximum;
+    if (value.storeMaximum !== undefined) {
+        if (!isNonEmptyString(value.storeMaximum))
+            return { error: "storeMaximum must be an allocator SUID" };
+        try {
+            decodeSuid(value.storeMaximum);
+        }
+        catch {
+            return { error: "storeMaximum must be an allocator SUID" };
+        }
+        storeMaximum = value.storeMaximum;
+    }
+    return { value: { importId: value.importId, leaseEpoch: value.leaseEpoch, highWatermark: value.highWatermark, ...(storeMaximum !== undefined ? { storeMaximum } : {}) } };
 }
 function newAllocatorLineageId() {
     // A fresh token is generated when the allocator has no durable state, so a
@@ -118,6 +132,7 @@ function allocateFrom(value) {
             ...(serviceId !== undefined ? { serviceId } : {}),
             ...(bootstrapCommandId !== undefined ? { bootstrapCommandId } : {}),
             ...(bootstrapEpoch !== undefined ? { bootstrapEpoch } : {}),
+            ...(value.requiresImportSeed === true ? { requiresImportSeed: true } : {}),
         },
     };
 }
@@ -519,6 +534,8 @@ export class AllocatorDurableObject {
                 const state = persistedState === undefined
                     ? currentState(lineage)
                     : { ...persistedState, allocatorLineageId: lineage, schemaVersion: 5, bootstrapSeed: persistedState.bootstrapSeed ?? null, lastRollbackWarningFingerprint: persistedState.lastRollbackWarningFingerprint ?? null };
+                if (input.requiresImportSeed === true && state.bootstrapSeed === null)
+                    throw new ImportSeedRequiredError();
                 // This is intentionally before the first transaction write. A clock
                 // failure therefore cannot leave a vector, watermark, or warning fact.
                 let clockTick;
@@ -609,6 +626,9 @@ export class AllocatorDurableObject {
             return json(result.vector, result.created ? 201 : 200);
         }
         catch (failure) {
+            if (failure instanceof ImportSeedRequiredError) {
+                return error(409, "allocator_seed_required", "commit before import seed");
+            }
             if (failure instanceof AllocationTransactionFault) {
                 return error(503, "simulated_allocation_crash", "Simulated interruption before durable allocation transaction commit");
             }
@@ -649,7 +669,10 @@ export class AllocatorDurableObject {
             }
             if (state.allocatedWatermark !== null)
                 return { status: 409, body: { code: "allocator_seed_rejected", error: "allocator already allocating" } };
-            const updated = { ...state, allocatedWatermark: input.highWatermark, bootstrapSeed: input };
+            if (input.storeMaximum !== undefined && input.highWatermark < input.storeMaximum) {
+                return { status: 409, body: { code: "allocator_seed_below_store_max", error: "seed below store maximum" } };
+            }
+            const updated = { ...state, allocatedWatermark: input.highWatermark, bootstrapSeed: { importId: input.importId, leaseEpoch: input.leaseEpoch, highWatermark: input.highWatermark } };
             await txn.put(STATE_KEY, updated);
             return { status: 201, body: updated };
         });

package/dist/bootstrap/BootstrapCoordinatorDurableObject.d.ts

@@ -23,6 +23,8 @@ export declare class BootstrapCoordinatorDurableObject implements DurableObject
     /** Operator abort retains the durable failed plan for audit/retry; it never clears target state. */
     private abort;
     private route;
+    private permit;
+    private permitRelease;
     private command;
 }
 export {};

package/dist/bootstrap/BootstrapCoordinatorDurableObject.js

@@ -13,13 +13,22 @@ const epoch = (value) => typeof value === "number" && Number.isSafeInteger(value
 const response = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json; charset=utf-8" } });
 const reject = (code, message, status = 409) => response({ code, error: message }, status);
 function empty(serviceId) {
-    return { schemaVersion: 1, status: "EMPTY", importId: null, targetServiceId: serviceId, allocatorLineageId: null, source: null, digest: null, manifest: null, progress: {}, leaseEpoch: 0, leaseUntil: null, failure: null, readyAt: null, normalInFlight: 0, normalCommands: {}, releasedCommands: {}, verifiedImportId: null, verifiedLeaseEpoch: null, storeCompletion: null };
+    return { schemaVersion: 1, status: "EMPTY", importId: null, targetServiceId: serviceId, allocatorLineageId: null, source: null, digest: null, manifest: null, progress: {}, leaseEpoch: 0, leaseUntil: null, failure: null, readyAt: null, normalInFlight: 0, normalCommands: {}, releasedCommands: {}, writePermits: {}, verifiedImportId: null, verifiedLeaseEpoch: null, storeCompletion: null };
 }
 function expired(control) { return control.leaseUntil !== null && control.leaseUntil <= Date.now(); }
 function commands(control) { return { ...(control.normalCommands ?? {}) }; }
 function released(control) { return { ...(control.releasedCommands ?? {}) }; }
+function permits(control) { return { ...(control.writePermits ?? {}) }; }
 function fault(body, point) { return object(body) && body.faultAt === point; }
 function encodedBytes(value) { return new TextEncoder().encode(JSON.stringify(value)).byteLength; }
+async function readBody(request) {
+    try {
+        return await request.json();
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Per-service authority and linearization point for bootstrap and normal writes. */
 export class BootstrapCoordinatorDurableObject {
     ctx;
@@ -48,6 +57,10 @@ export class BootstrapCoordinatorDurableObject {
             return this.traceCommand(request, serviceId, activation, observation, "finalize");
         if (request.method === "POST" && url.pathname === "/command/release")
             return this.traceCommand(request, serviceId, activation, observation, "release");
+        if (request.method === "POST" && url.pathname === "/command/permit")
+            return this.permit(serviceId, await readBody(request));
+        if (request.method === "POST" && url.pathname === "/command/permit-release")
+            return this.permitRelease(serviceId, await readBody(request));
         let body;
         try {
             body = await request.json();
@@ -119,6 +132,8 @@ export class BootstrapCoordinatorDurableObject {
                 return { error: "bootstrap_ready_permanent" };
             if (control.status !== "EMPTY")
                 return control.importId === importId && control.digest === dump.manifest.contentDigest ? { control } : { error: "bootstrap_plan_conflict" };
+            if (Object.keys(permits(control)).length !== 0)
+                return { error: "bootstrap_write_permit_active" };
             if (control.normalInFlight !== 0 || Object.keys(commands(control)).length !== 0)
                 return { error: "bootstrap_normal_command_in_flight" };
             const next = { ...control, status: "PLANNED", importId, allocatorLineageId: dump.manifest.target.allocatorLineageId, source: dump.manifest.source, digest: dump.manifest.contentDigest, manifest: dump.manifest, leaseEpoch: control.leaseEpoch + 1, leaseUntil: Date.now() + 30_000, failure: null, progress: {}, verifiedImportId: null, verifiedLeaseEpoch: null, storeCompletion: null };
@@ -315,6 +330,54 @@ export class BootstrapCoordinatorDurableObject {
         const control = await this.control(serviceId);
         return control.status === "EMPTY" || control.status === "READY" ? response({ admitted: true, leaseEpoch: control.leaseEpoch, route: body.route }) : reject("bootstrap_route_rejected", `${body.route} is unavailable during bootstrap`);
     }
+    async permit(serviceId, body) {
+        if (!object(body) || !string(body.commandId) || !string(body.digest))
+            return reject("bootstrap_permit_invalid", "commandId and digest are required", 400);
+        const commandId = body.commandId;
+        const digest = body.digest;
+        const result = await this.ctx.storage.transaction(async (txn) => {
+            const control = (await txn.get(CONTROL)) ?? empty(serviceId);
+            const active = permits(control);
+            if (active[commandId] !== undefined) {
+                return active[commandId] === digest
+                    ? { control }
+                    : { digestMismatch: true };
+            }
+            if (control.status !== "EMPTY" && control.status !== "READY")
+                return { rejected: true };
+            const updated = { ...control, writePermits: { ...active, [commandId]: digest } };
+            await txn.put(CONTROL, updated);
+            return { control: updated };
+        });
+        if ("digestMismatch" in result)
+            return reject("bootstrap_permit_digest_mismatch", "bootstrap permit digest does not match the held permit");
+        if ("rejected" in result)
+            return reject("bootstrap_command_rejected", "bootstrap epoch rejects normal durable mutation");
+        return response({ leaseEpoch: result.control.leaseEpoch, admitted: true });
+    }
+    async permitRelease(serviceId, body) {
+        if (!object(body) || !string(body.commandId))
+            return reject("bootstrap_permit_invalid", "commandId is required", 400);
+        const commandId = body.commandId;
+        const digest = string(body.digest) ? body.digest : undefined;
+        const result = await this.ctx.storage.transaction(async (txn) => {
+            const control = (await txn.get(CONTROL)) ?? empty(serviceId);
+            const active = permits(control);
+            if (active[commandId] !== undefined && digest !== undefined && active[commandId] !== digest) {
+                return { digestMismatch: true };
+            }
+            if (active[commandId] === undefined)
+                return { control };
+            const next = { ...active };
+            delete next[commandId];
+            const updated = { ...control, writePermits: next };
+            await txn.put(CONTROL, updated);
+            return { control: updated };
+        });
+        if ("digestMismatch" in result)
+            return reject("bootstrap_permit_digest_mismatch", "bootstrap permit digest does not match the held permit");
+        return response({ leaseEpoch: result.control.leaseEpoch, admitted: true });
+    }
     async command(serviceId, body, action, observation) {
         if (!object(body) || !string(body.commandId))
             return reject("bootstrap_command_invalid", "commandId is required", 400);

package/dist/bootstrap/OperatorBootstrap.d.ts

@@ -1,5 +1,7 @@
 import type { BootstrapManifest } from "./types";
 import type { StoreProvider, StoreProviderEnvironment } from "../store/provider";
+/** Missing and unconfigured stay indistinguishable from an unknown path. */
+export declare function authenticateOperatorBootstrap(request: Request, binding: unknown): Promise<Response | undefined>;
 export interface OperatorBootstrapEnv extends StoreProviderEnvironment {
     readonly BOOTSTRAP: DurableObjectNamespace;
     readonly ALLOCATOR: DurableObjectNamespace;
@@ -16,5 +18,7 @@ export interface OperatorBootstrapHooks {
         readonly manifest: BootstrapManifest;
     }) => Promise<void>;
 }
-/** Bearer-only operator lane. Incoming headers are never forwarded to a DO. */
+/** Authorized continuation. Authentication runs before this function. */
+export declare function handleAuthorizedOperatorBootstrap(request: Request, env: OperatorBootstrapEnv, storeProvider: StoreProvider, hooks?: OperatorBootstrapHooks): Promise<Response>;
+/** Bearer-only bootstrap lane. Incoming headers are never forwarded to a DO. */
 export declare function handleOperatorBootstrap(request: Request, env: OperatorBootstrapEnv, storeProvider: StoreProvider, hooks?: OperatorBootstrapHooks): Promise<Response>;

package/dist/bootstrap/OperatorBootstrap.js

@@ -1,22 +1,22 @@
 import { parseBootstrapDump } from "./manifest";
 import { createBootstrapStoreAdapter } from "./BootstrapStoreAdapter";
+import { checkConfiguredBearer } from "../http/ConfiguredBearer";
 import { scopeIdFor } from "../scope/ScopeName";
 function json(body, status = 200) { return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json; charset=utf-8" } }); }
 function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
-function bearer(request, token) {
-    const supplied = request.headers.get("authorization");
-    // Keep absence indistinguishable from an undiscovered management surface.
-    if (supplied === null)
+/** Missing and unconfigured stay indistinguishable from an unknown path. */
+export async function authenticateOperatorBootstrap(request, binding) {
+    const decision = await checkConfiguredBearer(request, binding);
+    if (decision === "unconfigured" || decision === "missing") {
         return json({ code: "not_found", error: "not found" }, 404);
-    if (supplied !== `Bearer ${token}`)
+    }
+    if (decision === "invalid") {
         return json({ code: "operator_auth_required", error: "valid bearer required" }, 403);
+    }
     return undefined;
 }
-/** Bearer-only operator lane. Incoming headers are never forwarded to a DO. */
-export async function handleOperatorBootstrap(request, env, storeProvider, hooks = {}) {
-    const denied = bearer(request, env.REPAIR_OPERATOR_TOKEN);
-    if (denied !== undefined)
-        return denied;
+/** Authorized continuation. Authentication runs before this function. */
+export async function handleAuthorizedOperatorBootstrap(request, env, storeProvider, hooks = {}) {
     const url = new URL(request.url);
     const match = url.pathname.match(/^\/operator\/bootstrap\/([^/]+)\/(plan|import|status|abort|export)$/);
     if (match === null)
@@ -102,3 +102,10 @@ export async function handleOperatorBootstrap(request, env, storeProvider, hooks
     }
     return invoke("/ready", body);
 }
+/** Bearer-only bootstrap lane. Incoming headers are never forwarded to a DO. */
+export async function handleOperatorBootstrap(request, env, storeProvider, hooks = {}) {
+    const denied = await authenticateOperatorBootstrap(request, env.REPAIR_OPERATOR_TOKEN);
+    if (denied !== undefined)
+        return denied;
+    return handleAuthorizedOperatorBootstrap(request, env, storeProvider, hooks);
+}

package/dist/bootstrap/types.d.ts

@@ -55,6 +55,12 @@ export interface BootstrapControlRecord {
     readonly normalCommands?: Readonly<Record<string, number>>;
     /** Recently released entry admissions, retained only for their final epoch check. */
     readonly releasedCommands?: Readonly<Record<string, number>>;
+    /**
+     * SDT-G36 durable write permits. Held from before allocation until every
+     * target tag of that attempt is durably resolved. Absent on old records
+     * (treated as `{}`). Only a bootstrap barrier, never commit authority.
+     */
+    readonly writePermits?: Readonly<Record<string, string>>;
     /** READY is a post-verification state, never merely an import completion. */
     readonly verifiedImportId?: string | null;
     readonly verifiedLeaseEpoch?: number | null;

package/dist/cli/OperatorRepairCli.d.ts

@@ -7,5 +7,10 @@ export interface OperatorRepairEnv {
     REPAIR_EXCLUSION_LOOKUP?: Fetcher;
     SDT_SERVICE_ID?: string;
 }
-/** Authenticated, bounded control-plane command; it is not a V1 public wire endpoint. */
+/** Non-POST stays a route miss for every binding state, before authentication. */
+export declare function nonPostOperatorRepairResponse(request: Request): Response | undefined;
+export declare function authenticateOperatorRepair(request: Request, binding: unknown): Promise<Response | undefined>;
+/** Authorized continuation. Authentication and the POST check run before this. */
+export declare function handleAuthorizedOperatorRepair(request: Request, env: OperatorRepairEnv, nativeTracing?: NativeTracing, serviceIdentityProvider?: ServiceIdentityProvider): Promise<Response>;
+/** Authenticated, bounded repair command; it is not a V1 public wire endpoint. */
 export declare function handleOperatorRepair(request: Request, env: OperatorRepairEnv, nativeTracing?: NativeTracing, serviceIdentityProvider?: ServiceIdentityProvider): Promise<Response>;

package/dist/cli/OperatorRepairCli.js

@@ -1,4 +1,5 @@
 import { BindingExclusionLookupClient } from "../downstream/ExclusionLookup";
+import { checkConfiguredBearer } from "../http/ConfiguredBearer";
 import { RepairWorker, RepairWorkerFailure } from "../repair/RepairWorker";
 import { noOpNativeTracing } from "../trace/CommitTrace";
 import { envServiceIdentity, requireServiceIdentity } from "../service/ServiceIdentityProvider";
@@ -74,15 +75,24 @@ function testFaultFromRequest(request) {
         ? value
         : undefined;
 }
-/** Authenticated, bounded control-plane command; it is not a V1 public wire endpoint. */
-export async function handleOperatorRepair(request, env, nativeTracing = noOpNativeTracing, serviceIdentityProvider) {
-    if (request.method !== "POST") {
-        return error(404, "operator_repair_route_not_found", "Operator repair requires POST");
+/** Non-POST stays a route miss for every binding state, before authentication. */
+export function nonPostOperatorRepairResponse(request) {
+    if (request.method === "POST")
+        return undefined;
+    return error(404, "operator_repair_route_not_found", "Operator repair requires POST");
+}
+export async function authenticateOperatorRepair(request, binding) {
+    const decision = await checkConfiguredBearer(request, binding);
+    if (decision === "unconfigured") {
+        return error(404, "operator_repair_route_not_found", "Operator repair route not found");
     }
-    const token = env.REPAIR_OPERATOR_TOKEN;
-    if (!isNonEmptyString(token) || request.headers.get("authorization") !== `Bearer ${token}`) {
+    if (decision === "missing" || decision === "invalid") {
         return error(401, "operator_auth_required", "A valid operator repair bearer token is required");
     }
+    return undefined;
+}
+/** Authorized continuation. Authentication and the POST check run before this. */
+export async function handleAuthorizedOperatorRepair(request, env, nativeTracing = noOpNativeTracing, serviceIdentityProvider) {
     let body;
     try {
         body = await request.json();
@@ -106,3 +116,13 @@ export async function handleOperatorRepair(request, env, nativeTracing = noOpNat
         return error(500, "operator_repair_failed", message);
     }
 }
+/** Authenticated, bounded repair command; it is not a V1 public wire endpoint. */
+export async function handleOperatorRepair(request, env, nativeTracing = noOpNativeTracing, serviceIdentityProvider) {
+    const methodDenied = nonPostOperatorRepairResponse(request);
+    if (methodDenied !== undefined)
+        return methodDenied;
+    const denied = await authenticateOperatorRepair(request, env.REPAIR_OPERATOR_TOKEN);
+    if (denied !== undefined)
+        return denied;
+    return handleAuthorizedOperatorRepair(request, env, nativeTracing, serviceIdentityProvider);
+}

package/dist/cloudflare.d.ts

@@ -30,6 +30,8 @@ export { buildScopeName, DURABLE_OBJECT_SCOPE_CLASSES, isScopeServiceId, parseSc
 export type { DurableObjectScope, DurableObjectScopeClass, ScopeNameNamespace } from "./scope/ScopeName";
 export { envServiceIdentity, G11_SERVICE_ID_HEADER, injectableServiceIdentity, requestServiceIdentity, requireServiceIdentity, ServiceIdentityMissingError, TEST_SERVICE_ID_HEADER, } from "./service/ServiceIdentityProvider";
 export type { ServiceIdentityBehavior, ServiceIdentityEnvironment, ServiceIdentityProvider, ServiceIdentityRequestOptions, ServiceIdentityResolution, } from "./service/ServiceIdentityProvider";
+export { checkConfiguredBearer } from "./http/ConfiguredBearer";
+export type { CheckConfiguredBearerOptions, ConfiguredBearerResult, ConfiguredBearerTokenNormalization, } from "./http/ConfiguredBearer";
 export interface CloudflareOnlyEnv {
     ALLOCATOR: DurableObjectNamespace;
     BOOTSTRAP: DurableObjectNamespace;
@@ -42,6 +44,7 @@ export interface CloudflareOnlyEnv {
     D1_MV: D1Database;
     AUTO_DRAIN_OUTBOX?: string;
     REPAIR_OPERATOR_TOKEN: string;
+    INCIDENT_MAINTAINER_TOKEN?: string;
     REPAIR_EXCLUSION_LOOKUP?: Fetcher;
     G11_VERIFICATION_ENABLED?: string;
     SDT_SERVICE_ID?: string;
@@ -152,6 +155,8 @@ export type { ClosedPrefixCertificate } from "./allocator/types";
 export type { SafeViewCoverageContext } from "./projection/ProjectionRuntime";
 export { downstreamEnvelopeBytes, classifyDirectDoorbellFailure, preflightDirectDoorbell, readDomainDeliveryClass, readDirectDoorbellConfig, selectDirectDoorbellViews, MAX_SERVICE_BINDING_INVOCATIONS_PER_REQUEST, } from "./downstream/Doorbell";
 export { deliveryCorrelationId } from "./downstream/DeliveryCore";
+export { admitActiveWrite, assertNoSilentLedgerMerge, assertStrictlyBefore, createRotationState, maxSortableUniqueId, recordLateArrival, refuseSafeWindowSeal, refuseSealedWrite, refuseSilentLedgerMerge, replaceSealedIdentity, rotateAppend, ShardRotationError, } from "./shard/ShardRotation";
+export type { LateArrival, SealedShard, ShardRotationDiagnostic, ShardRotationState, } from "./shard/ShardRotation";
 export { GlobalCompletenessReconciler } from "./completeness/GlobalCompletenessReconciler";
 export { G44_HEALTH_STALE_AFTER_MS, G44_SCANNER_VERSION, GLOBAL_COMPLETENESS_INTERIM_DISPOSITION, } from "./completeness/types";
 export type { GlobalCompletenessHealth, GlobalCompletenessCoverage, GlobalCompletenessHealthRecord, GlobalCompletenessScanResult, SourceObligationFact, SourceObligationPage, SourcePartitionSnapshot, } from "./completeness/types";