@swirls/looms 0.3.0 → 0.5.0

package/dist/runtime/runtime.js

@@ -1,8 +1,8 @@
 import { Clock, Effect, ManagedRuntime, Predicate } from 'effect';
-import { composeModules, createEvent, createThreadId, createRunId, DEFAULT_DEFINITION_VERSION, DEFAULT_SNAPSHOT_EVERY, definitionKey, descendantThreadIds, EventStoreTag, foldRun, isRunTerminal, planFork, project, replayTo, summarizeRun, } from '@swirls/looms/core';
+import { cachedDefinitionResolver, chainDefinitionResolvers, composeModules, createEvent, createThreadId, createRunId, DEFAULT_DEFINITION_VERSION, DEFAULT_SNAPSHOT_EVERY, staticDefinitionResolver, descendantThreadIds, EventStoreTag, foldRun, hasEntries, isRunTerminal, unavailableRunLauncher, planFork, project, readTraceContext, replayTo, sameStringRecord, summarizeRun, } from '@swirls/looms/core';
 import { createCancellation } from './cancellation.js';
 import { nextRuntimeDeadline } from './deadline-transition-planner.js';
-import { ForkConflictError, RunNotFinishedError, RunNotFoundError, RunTerminalError, RuntimeExecutionError, } from './errors.js';
+import { ForkConflictError, RunNotFinishedError, RunNotFoundError, RunTerminalError, RuntimeExecutionError, SecretContextConflictError, StartRunConflictError, } from './errors.js';
 import { admitExternalEvents, moduleServices, resolveSnapshotStore, RunCursorCache, threadStartedEvents, UnknownDefinitionError, validateAndCreateEvents, waitSatisfiedEvents, } from './helpers.js';
 import { createRunIngress } from './ingress.js';
 import { notifyObserver } from './observer.js';
@@ -12,6 +12,7 @@ import { assertSameDurableStart } from './run-start.js';
 import { createWakeEngine } from './wake-engine.js';
 import { createTimeoutScheduler } from './wake-scheduler.js';
 import { createWorkerCallbacks } from './worker-callbacks.js';
+import { assertWorkerDeadlines } from './worker-effect-dispatch.js';
 export { createTimeoutScheduler } from './wake-scheduler.js';
 export { DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunTerminalError, StartRunConflictError, } from './errors.js';
 export { RunOverloadedError } from './ingress.js';
@@ -33,10 +34,64 @@ const DEFAULT_RUN_CACHE_SIZE = 0;
 const RESCAN_CONCURRENCY = 16;
 const DEFAULT_KEEP_SNAPSHOTS = 1;
 const DEFAULT_MAX_PENDING_RUN_OPERATIONS = 256;
+function startedPayload(input) {
+    const payload = {
+        rootThreadId: input.threadId,
+        kind: input.kind,
+        definitionName: input.definitionName,
+        definitionVersion: input.definitionVersion,
+        input: input.input ?? null,
+        requestedThreadId: input.requestedThreadId,
+    };
+    if (input.launchedBy) {
+        payload.launchedBy = input.launchedBy;
+    }
+    if (input.attributes && hasEntries(input.attributes)) {
+        payload.attributes = input.attributes;
+    }
+    if (input.trace) {
+        payload.trace = input.trace;
+    }
+    return payload;
+}
+function reconcileRunSecrets(store, runId, requested) {
+    const next = requested ?? {};
+    return Effect.gen(function* () {
+        const stored = store.runSecrets;
+        if (!stored) {
+            if (hasEntries(next)) {
+                return yield* new RuntimeExecutionError('This event store cannot persist a secret context');
+            }
+            return yield* Effect.void;
+        }
+        const current = yield* stored.get(runId);
+        if (sameStringRecord(current, next) || requested === undefined) {
+            return yield* Effect.void;
+        }
+        if (!hasEntries(current)) {
+            return yield* stored.put(runId, next);
+        }
+        return yield* new SecretContextConflictError(runId);
+    });
+}
 export function createRuntime(options) {
+    if (options.localLauncher && !options.store && !options.launcher) {
+        throw new Error('localLauncher requires options.store');
+    }
     const registry = composeModules(options.modules);
-    const registeredDefinitions = registry.definitions;
-    const definitions = new Map(registeredDefinitions.map((def) => [definitionKey(def.kind, def.name, def.version), def]));
+    assertWorkerDeadlines(registry, options.worker);
+    const staticResolver = staticDefinitionResolver(registry.definitions.map((definition) => ({
+        ...definition.value,
+        kind: definition.kind,
+        name: definition.name,
+        version: definition.version,
+    })));
+    const definitionResolver = cachedDefinitionResolver(options.definitionResolver
+        ? chainDefinitionResolvers([staticResolver, options.definitionResolver])
+        : staticResolver);
+    for (const module of options.modules) {
+        module.bindHost?.({ definitionResolver });
+    }
     // Module composition erases the heterogeneous service identifier union at this host boundary.
     // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context
     const services = ManagedRuntime.make(moduleServices(options.modules));
@@ -58,6 +113,7 @@ export function createRuntime(options) {
         runCache,
         executionContexts,
         observer: options.observer,
+        definitionResolver,
     });
     const { commit, loadCursor } = repository;
     const signalAdmitted = (runId, events, signalOpts) => Effect.gen(function* () {
@@ -77,12 +133,17 @@ export function createRuntime(options) {
             const batch = yield* validateAndCreateEvents(registry.catalogs, runId, filteredEvents.map((input) => ({
                 ...input,
                 idempotencyKey: input.idempotencyKey ?? signalKey,
-            })), { origin: { type: 'external' } });
-            if (isRunTerminal(current.state)) {
+            })), { origin: { type: 'external' }, threadId: current.state.rootThreadId });
+            const terminal = isRunTerminal(current.state);
+            const settlementOnly = filteredEvents.every((event) => event.type === 'runtime.child.settled');
+            if (terminal && !settlementOnly) {
                 return yield* new RunTerminalError(runId, current.state.status);
             }
             const folded = foldRun(batch, registry, { runId, initial: current.state });
-            const satisfiedEvents = waitSatisfiedEvents(folded, batch).map((input) => createEvent(runId, input));
+            const forWaits = terminal || current.state.closeWaiting
+                ? batch.filter((event) => event.type !== 'runtime.child.settled')
+                : batch;
+            const satisfiedEvents = waitSatisfiedEvents(folded, forWaits).map((input) => createEvent(runId, input));
             return {
                 events: [...batch, ...satisfiedEvents],
                 value: current.state,
@@ -94,19 +155,100 @@ export function createRuntime(options) {
         }
         return committed.value;
     });
+    const commitStart = (args, runId) => Effect.gen(function* () {
+        const definitionVersion = args.definitionVersion ?? DEFAULT_DEFINITION_VERSION;
+        const resolved = yield* definitionResolver.resolve(args.kind, args.definitionName, definitionVersion);
+        if (!resolved) {
+            return yield* new UnknownDefinitionError(args.kind, args.definitionName, definitionVersion);
+        }
+        const store = yield* EventStoreTag;
+        observe({ type: 'run.start', runId, at: currentTimeMillis() });
+        const threadId = args.threadId ?? createThreadId();
+        const startedEvents = yield* threadStartedEvents(definitionResolver, {
+            kind: args.kind,
+            definitionName: args.definitionName,
+            definitionVersion,
+            input: args.input ?? null,
+            threadId,
+            parentThreadId: null,
+        });
+        const started = startedEvents[0];
+        const startedInput = started && Predicate.isObject(started.payload)
+            ? (started.payload.input ?? null)
+            : (args.input ?? null);
+        const requestedIdentity = {
+            kind: args.kind,
+            definitionName: args.definitionName,
+            definitionVersion,
+            input: startedInput,
+            requestedThreadId: args.threadId ?? null,
+            idempotencyKey: args.idempotencyKey ?? null,
+            launchedBy: args.launchedBy ?? null,
+            correlationId: args.correlationId ?? null,
+            attributes: args.attributes ?? {},
+        };
+        const origin = args.launchedBy
+            ? { type: 'run', runId: args.launchedBy.runId }
+            : { type: 'system' };
+        const startPayload = startedPayload({
+            threadId,
+            kind: args.kind,
+            definitionName: args.definitionName,
+            definitionVersion,
+            input: startedInput,
+            requestedThreadId: args.threadId ?? null,
+            launchedBy: args.launchedBy,
+            attributes: args.attributes,
+            trace: args.trace && readTraceContext(args.trace.traceparent, args.trace.tracestate),
+        });
+        if (hasEntries(args.secrets ?? {}) && !store.runSecrets) {
+            return yield* new RuntimeExecutionError('This event store cannot persist a secret context');
+        }
+        const committed = yield* commit(store, runId, (existing) => existing.seq > 0
+            ? assertSameDurableStart(runId, existing.state, requestedIdentity).pipe(Effect.map((rootThreadId) => ({
+                events: [],
+                value: { threadId: rootThreadId, state: existing.state },
+            })))
+            : validateAndCreateEvents(registry.catalogs, runId, [
+                {
+                    type: 'runtime.run.started',
+                    payload: startPayload,
+                    threadId: null,
+                    idempotencyKey: args.idempotencyKey,
+                },
+                ...startedEvents,
+            ].map((event) => ({ ...event, correlationId: args.correlationId })), { origin }).pipe(Effect.map((batch) => ({
+                events: batch,
+                value: {
+                    threadId,
+                    state: foldRun(batch, registry, { runId, initial: existing.state }),
+                },
+                idempotencyKey: args.idempotencyKey ? `start:${args.idempotencyKey}` : undefined,
+            }))));
+        yield* reconcileRunSecrets(store, runId, args.secrets);
+        if (!committed.append?.deduplicated) {
+            return committed.value;
+        }
+        const durable = yield* loadCursor(store, runId);
+        const rootThreadId = yield* assertSameDurableStart(runId, durable.state, requestedIdentity);
+        return { threadId: rootThreadId, state: durable.state };
+    });
     let scheduler;
+    let launcher;
     let runtime;
     const wakeEngine = createWakeEngine({
         registry,
         services,
-        definitions,
         executionContexts,
         repository,
         snapshotEvery,
         maxWakeIterations,
+        maxInFlightWorkerEffects: options.maxInFlightWorkerEffects,
         worker: options.worker,
         observer: options.observer,
+        definitionResolver,
         scheduler: () => scheduler,
+        launcher: () => launcher,
     });
     const workerCallbacks = createWorkerCallbacks({
         registry,
@@ -123,7 +265,15 @@ export function createRuntime(options) {
         observer: options.observer,
         wake: wakeEngine,
         withRunIngress,
+        launcher: () => launcher,
     });
+    const appendAndWake = (runId, events, signalOpts) => withRunIngress(runId, signalAdmitted(runId, events, signalOpts)).pipe(Effect.flatMap((state) => {
+        if (signalOpts?.coalesce && executionContexts.get(runId).waking) {
+            executionContexts.get(runId).wakeAgain = true;
+            return Effect.succeed(state);
+        }
+        return runtime.wake(runId);
+    }));
     runtime = {
         modules: options.modules,
         registry,
@@ -228,70 +378,28 @@ export function createRuntime(options) {
         recoverDeadlines: Effect.suspend(() => runtime.rescanTimers),
         startRun: (args) => {
             const runId = args.runId ?? createRunId();
-            return withRunIngress(runId, Effect.gen(function* () {
-                const definitionVersion = args.definitionVersion ?? DEFAULT_DEFINITION_VERSION;
-                if (!definitions.get(definitionKey(args.kind, args.definitionName, definitionVersion))) {
-                    return yield* new UnknownDefinitionError(args.kind, args.definitionName, definitionVersion);
-                }
-                const store = yield* EventStoreTag;
-                observe({ type: 'run.start', runId, at: currentTimeMillis() });
-                const threadId = args.threadId ?? createThreadId();
-                const startedEvents = yield* threadStartedEvents(definitions, {
-                    kind: args.kind,
-                    definitionName: args.definitionName,
-                    definitionVersion,
-                    input: args.input ?? null,
-                    threadId,
-                    parentThreadId: null,
-                });
-                const started = startedEvents[0];
-                const startedInput = started && Predicate.isObject(started.payload)
-                    ? (started.payload.input ?? null)
-                    : (args.input ?? null);
-                const requestedIdentity = {
-                    kind: args.kind,
-                    definitionName: args.definitionName,
-                    definitionVersion,
-                    input: startedInput,
-                    requestedThreadId: args.threadId ?? null,
-                    idempotencyKey: args.idempotencyKey ?? null,
-                };
-                const committed = yield* commit(store, runId, (existing) => existing.seq > 0
-                    ? assertSameDurableStart(runId, existing.state, requestedIdentity).pipe(Effect.map((rootThreadId) => ({ events: [], value: rootThreadId })))
-                    : validateAndCreateEvents(registry.catalogs, runId, [
-                        {
-                            type: 'runtime.run.started',
-                            payload: {
-                                rootThreadId: threadId,
-                                kind: args.kind,
-                                definitionName: args.definitionName,
-                                definitionVersion,
-                                input: startedInput,
-                                requestedThreadId: args.threadId ?? null,
-                            },
-                            threadId: null,
-                            idempotencyKey: args.idempotencyKey,
-                        },
-                        ...startedEvents,
-                    ], { origin: { type: 'system' } }).pipe(Effect.map((batch) => ({
-                        events: batch,
-                        value: threadId,
-                        idempotencyKey: args.idempotencyKey
-                            ? `start:${args.idempotencyKey}`
-                            : undefined,
-                    }))));
-                if (!committed.append?.deduplicated) {
-                    return committed.value;
-                }
-                const durable = yield* loadCursor(store, runId);
-                return yield* assertSameDurableStart(runId, durable.state, requestedIdentity);
-            })).pipe(Effect.flatMap((threadId) => runtime.wake(runId).pipe(Effect.map((state) => ({
+            return withRunIngress(runId, commitStart(args, runId)).pipe(Effect.flatMap((started) => runtime.wake(runId).pipe(Effect.map((state) => ({
                 runId,
-                threadId: state.rootThreadId ?? threadId,
+                threadId: state.rootThreadId ?? started.threadId,
                 state,
             })))));
         },
-        signal: (runId, events, signalOpts) => admitExternalEvents(events).pipe(Effect.flatMap((admitted) => withRunIngress(runId, signalAdmitted(runId, admitted, signalOpts))), Effect.andThen(runtime.wake(runId))),
+        launchRun: (args) => {
+            const runId = args.runId ?? createRunId();
+            return withRunIngress(runId, commitStart(args, runId)).pipe(Effect.flatMap((started) => Effect.gen(function* () {
+                if (!isRunTerminal(started.state)) {
+                    const now = yield* Clock.currentTimeMillis;
+                    yield* scheduler.schedule(runId, now);
+                }
+                return {
+                    runId,
+                    threadId: started.state.rootThreadId ?? started.threadId,
+                    state: started.state,
+                };
+            })));
+        },
+        signal: (runId, events, signalOpts) => admitExternalEvents(events).pipe(Effect.flatMap((admitted) => appendAndWake(runId, admitted, signalOpts))),
+        accept: (runId, events, signalOpts) => appendAndWake(runId, events, signalOpts),
         cancel: cancellation,
         fork: (sourceRunId, forkOptions) => {
             const runId = forkOptions?.runId ?? createRunId();
@@ -319,6 +427,8 @@ export function createRuntime(options) {
                         ? Effect.succeed({ events: [], value: undefined })
                         : Effect.fail(new ForkConflictError(runId, sourceRunId));
                 });
+                const parentSecrets = store.runSecrets ? yield* store.runSecrets.get(sourceRunId) : {};
+                yield* reconcileRunSecrets(store, runId, hasEntries(parentSecrets) ? parentSecrets : undefined);
                 return plan.rootThreadId;
             })).pipe(Effect.flatMap((threadId) => runtime.wake(runId).pipe(Effect.map((state) => ({ runId, threadId, state })))));
         },
@@ -332,5 +442,18 @@ export function createRuntime(options) {
                     .wake(runId)
                     .pipe(Effect.provideService(EventStoreTag, options.store), Effect.tapError(Effect.logError), Effect.ignore)
                 : Effect.void);
+    const store = options.store;
+    launcher =
+        options.launcher ??
+            (options.localLauncher && store
+                ? {
+                    launch: (args) => runtime.launchRun(args).pipe(Effect.provideService(EventStoreTag, store), Effect.catchIf((error) => error instanceof StartRunConflictError, () => Effect.void), Effect.asVoid),
+                    status: (runId) => runtime.getRun(runId).pipe(Effect.provideService(EventStoreTag, store), Effect.map((state) => state.rootThreadId === null ? null : { status: state.status })),
+                    signal: (runId, events, signalOptions) => runtime
+                        .accept(runId, events, { ...signalOptions, coalesce: true })
+                        .pipe(Effect.provideService(EventStoreTag, store), Effect.asVoid),
+                    cancel: (runId) => runtime.cancel(runId).pipe(Effect.provideService(EventStoreTag, store), Effect.asVoid),
+                }
+                : unavailableRunLauncher);
     return runtime;
 }

package/dist/runtime/server/auth.d.ts

@@ -1,4 +1,5 @@
 import { Effect } from 'effect';
+import type { RunAttributes } from '@swirls/looms/core';
 /**
  * What a route can do. `public` routes (health) are never passed to `authorize`; `read` and
  * `write` cover run state, `worker` covers external worker callbacks, and `operations` covers
@@ -11,6 +12,8 @@ export interface RouteInfo {
     /** Stable route name, such as `runs.signal` or `effects.retry`. */
     readonly name: string;
     readonly runId?: string;
+    /** Present when the run has labels. Safe for the authorizer to branch on. */
+    readonly attributes?: RunAttributes;
 }
 export type AuthDecision = {
     readonly allowed: true;

package/dist/runtime/server/fetch-handler.d.ts

@@ -1,4 +1,4 @@
-import type { EventStore } from '@swirls/looms/core';
+import { type EventStore } from '@swirls/looms/core';
 import type { LoomsRuntime } from '../runtime';
 import { type Authorize } from './auth';
 import { type DebuggerMount } from './debugger-host';
@@ -7,7 +7,7 @@ export interface FetchHandlerOptions {
     readonly store: EventStore;
     /**
      * Decides whether a request may use a route. Defaults to open reads and writes with worker and
-     * operations routes unavailable; use `bearerAuth` or your own policy to change that.
+     * operations routes unavailable; use `bearerAuth`, `grantAuth`, or your own policy to change that.
      */
     readonly authorize?: Authorize;
     /** Debugger UI served beside the API and authorized as `{ access: 'read', name: 'debugger' }`. */

package/dist/runtime/server/fetch-handler.js

@@ -1,4 +1,5 @@
-import { Effect, Predicate } from 'effect';
+import { Data, Effect, Option, Predicate, Schema } from 'effect';
+import { hasEntries, RunAttributesSchema } from '@swirls/looms/core';
 import { authResponse, defaultAuthorize } from './auth.js';
 import { debuggerPath, serveDebugger } from './debugger-host.js';
 import { acceptsEventStream, isLoomsApiPath, toErrorResponse } from './http.js';
@@ -7,6 +8,7 @@ import { definitionRoutes } from './routes/definitions.js';
 import { effectRoutes } from './routes/effects.js';
 import { operationRoutes } from './routes/operations.js';
 import { runRoutes } from './routes/runs.js';
+import { readStoredAttributes } from './run-route.js';
 function createRoutes(options) {
     return [
         ...definitionRoutes(options),
@@ -15,13 +17,42 @@ function createRoutes(options) {
         ...operationRoutes(options),
     ];
 }
-function authorizeRoute(req, matched, authorize) {
+const StartAttributesSchema = Schema.Struct({
+    attributes: Schema.optional(RunAttributesSchema),
+});
+class UnreadableStartBody extends Data.TaggedError('UnreadableStartBody') {
+}
+const noAttributes = {};
+function readRequestAttributes(req) {
+    return Effect.tryPromise({
+        try: () => req.clone().json(),
+        catch: (cause) => new UnreadableStartBody({ cause }),
+    }).pipe(Effect.map((body) => Option.match(Schema.decodeUnknownOption(StartAttributesSchema)(body), {
+        onNone: () => noAttributes,
+        onSome: (decoded) => decoded.attributes ?? noAttributes,
+    })), Effect.catchTag('UnreadableStartBody', () => Effect.succeed(noAttributes)));
+}
+function authorizeRoute(req, matched, authorize, runtime, store) {
     const { access, name } = matched.route;
     if (access === 'public') {
         return Effect.succeed(null);
     }
     const runId = matched.params.runId;
-    return authorize(req, Predicate.isString(runId) ? { access, name, runId } : { access, name }).pipe(Effect.map(authResponse));
+    return Effect.gen(function* () {
+        const stored = Predicate.isString(runId)
+            ? yield* readStoredAttributes(runtime, store, runId)
+            : noAttributes;
+        const requested = matched.route.name === 'runs.start' ? yield* readRequestAttributes(req) : noAttributes;
+        const attributes = hasEntries(stored) ? stored : requested;
+        const route = Predicate.isString(runId)
+            ? hasEntries(attributes)
+                ? { access, name, runId, attributes }
+                : { access, name, runId }
+            : hasEntries(attributes)
+                ? { access, name, attributes }
+                : { access, name };
+        return yield* authorize(req, route).pipe(Effect.map(authResponse));
+    });
 }
 /** Whether the fetch handler answers `pathname`: the HTTP API or the debugger mount. */
 export function handlesPath(pathname, mount) {
@@ -49,7 +80,7 @@ export function createFetchHandler(options) {
             if (!matched) {
                 return new Response('Not Found', { status: 404 });
             }
-            const denied = yield* authorizeRoute(req, matched, authorize);
+            const denied = yield* authorizeRoute(req, matched, authorize, options.runtime, options.store);
             if (denied) {
                 return denied;
             }

package/dist/runtime/server/grant.d.ts

@@ -0,0 +1,49 @@
+import { Effect } from 'effect';
+import { type Authorize } from './auth';
+export type GrantFailure = 'malformed' | 'signature' | 'expired' | 'claims';
+declare const GrantError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "GrantError";
+} & Readonly<A>;
+export declare class GrantError extends GrantError_base<{
+    readonly reason: GrantFailure;
+}> {
+}
+/** Claims carried by a run grant. `exp` is an exclusive expiry in Unix milliseconds. */
+export interface RunGrant {
+    readonly runId: string;
+    readonly principal: string;
+    readonly access: 'read';
+    readonly exp: number;
+}
+export interface GrantAuthOptions {
+    readonly secret: string;
+    /** Clock used for expiry. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /**
+     * Extra time after `exp` that still verifies. Covers clock skew between the issuer and the host.
+     * Defaults to 0.
+     */
+    readonly clockSkewMs?: number;
+}
+/**
+ * Signs a read grant for one run. The token is URL-safe and is also a legal WebSocket subprotocol
+ * value, so a browser can send it as a query parameter or as `Sec-WebSocket-Protocol`.
+ */
+export declare function issueRunGrant(secret: string, claims: RunGrant): Effect.Effect<string, GrantError>;
+/** Verifies the HMAC and expiry. A grant for another run fails later, when a route is checked. */
+export declare function verifyRunGrant(secret: string, token: string, now: number, clockSkewMs?: number): Effect.Effect<RunGrant, GrantError>;
+/**
+ * Authorizes a read of the granted run. The token comes from the `grant` query parameter, or, when
+ * that is absent, from a `v1.` WebSocket subprotocol. Writes, worker callbacks, operations, and
+ * reads of any other run are refused. A host that accepts the subprotocol has to echo it on the
+ * WebSocket response; see `grantSubprotocol`.
+ */
+export declare function grantAuth(options: GrantAuthOptions): Authorize;
+/** The grant token on this request, if the client sent one. */
+export declare function runGrantToken(request: Request): string | undefined;
+/**
+ * The `v1.` grant the client offered as a WebSocket subprotocol. The upgrade response must echo it,
+ * or the browser fails the handshake.
+ */
+export declare function grantSubprotocol(request: Request): string | undefined;
+export {};

package/dist/runtime/server/grant.js

@@ -0,0 +1,177 @@
+import { Data, Effect, Option, Schema } from 'effect';
+import { authAllowed, authDenied } from './auth.js';
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const unauthorized = authDenied(401, 'Unauthorized');
+const forbidden = authDenied(403, 'Forbidden');
+const GrantPayloadSchema = Schema.Struct({
+    v: Schema.Literal(1),
+    runId: Schema.String,
+    principal: Schema.String,
+    access: Schema.Literal('read'),
+    exp: Schema.Finite,
+});
+const GrantPayloadJson = Schema.fromJsonString(GrantPayloadSchema);
+const encodeGrantPayload = Schema.encodeSync(GrantPayloadJson);
+const decodeGrantPayload = Schema.decodeUnknownOption(GrantPayloadJson);
+export class GrantError extends Data.TaggedError('GrantError') {
+}
+/**
+ * Signs a read grant for one run. The token is URL-safe and is also a legal WebSocket subprotocol
+ * value, so a browser can send it as a query parameter or as `Sec-WebSocket-Protocol`.
+ */
+export function issueRunGrant(secret, claims) {
+    return Effect.gen(function* () {
+        const payload = grantPayload(claims);
+        if (!payload) {
+            return yield* new GrantError({ reason: 'claims' });
+        }
+        const json = yield* Effect.try({
+            try: () => encodeGrantPayload(payload),
+            catch: () => new GrantError({ reason: 'claims' }),
+        });
+        const encoded = encodeBase64Url(textEncoder.encode(json));
+        const key = yield* importHmacKey(secret);
+        const signature = yield* Effect.tryPromise({
+            try: () => crypto.subtle.sign('HMAC', key, textEncoder.encode(encoded)),
+            catch: () => new GrantError({ reason: 'signature' }),
+        });
+        return `v1.${encoded}.${encodeBase64Url(new Uint8Array(signature))}`;
+    });
+}
+/** Verifies the HMAC and expiry. A grant for another run fails later, when a route is checked. */
+export function verifyRunGrant(secret, token, now, clockSkewMs = 0) {
+    return Effect.gen(function* () {
+        const parts = token.split('.');
+        if (parts.length !== 3 || parts[0] !== 'v1') {
+            return yield* new GrantError({ reason: 'malformed' });
+        }
+        const encoded = parts[1] ?? '';
+        const signature = decodeBase64Url(parts[2] ?? '');
+        const payloadBytes = decodeBase64Url(encoded);
+        if (!signature || !payloadBytes) {
+            return yield* new GrantError({ reason: 'malformed' });
+        }
+        const key = yield* importHmacKey(secret);
+        const authentic = yield* Effect.tryPromise({
+            try: () => crypto.subtle.verify('HMAC', key, signature, textEncoder.encode(encoded)),
+            catch: () => new GrantError({ reason: 'signature' }),
+        });
+        if (!authentic) {
+            return yield* new GrantError({ reason: 'signature' });
+        }
+        const decoded = decodeGrantPayload(textDecoder.decode(payloadBytes));
+        if (Option.isNone(decoded) ||
+            decoded.value.runId.length === 0 ||
+            decoded.value.principal.length === 0) {
+            return yield* new GrantError({ reason: 'claims' });
+        }
+        const skew = finiteSkew(clockSkewMs);
+        if (decoded.value.exp <= now - skew) {
+            return yield* new GrantError({ reason: 'expired' });
+        }
+        return {
+            runId: decoded.value.runId,
+            principal: decoded.value.principal,
+            access: decoded.value.access,
+            exp: decoded.value.exp,
+        };
+    });
+}
+/**
+ * Authorizes a read of the granted run. The token comes from the `grant` query parameter, or, when
+ * that is absent, from a `v1.` WebSocket subprotocol. Writes, worker callbacks, operations, and
+ * reads of any other run are refused. A host that accepts the subprotocol has to echo it on the
+ * WebSocket response; see `grantSubprotocol`.
+ */
+export function grantAuth(options) {
+    const now = options.now ?? Date.now;
+    const skew = finiteSkew(options.clockSkewMs);
+    return (request, route) => Effect.gen(function* () {
+        const token = runGrantToken(request);
+        if (token === undefined) {
+            return unauthorized;
+        }
+        return yield* verifyRunGrant(options.secret, token, now(), skew).pipe(Effect.map((grant) => grantDecision(grant, route)), Effect.catchTag('GrantError', () => Effect.succeed(unauthorized)));
+    });
+}
+/** The grant token on this request, if the client sent one. */
+export function runGrantToken(request) {
+    const query = new URL(request.url).searchParams.get('grant');
+    if (query) {
+        return query;
+    }
+    return grantSubprotocol(request);
+}
+/**
+ * The `v1.` grant the client offered as a WebSocket subprotocol. The upgrade response must echo it,
+ * or the browser fails the handshake.
+ */
+export function grantSubprotocol(request) {
+    return websocketGrant(request.headers.get('sec-websocket-protocol'));
+}
+function grantDecision(grant, route) {
+    if (route.access !== 'read' || route.runId !== grant.runId) {
+        return forbidden;
+    }
+    return authAllowed;
+}
+function grantPayload(claims) {
+    if (claims.runId.length === 0 || claims.principal.length === 0 || !Number.isFinite(claims.exp)) {
+        return undefined;
+    }
+    return {
+        v: 1,
+        runId: claims.runId,
+        principal: claims.principal,
+        access: 'read',
+        exp: claims.exp,
+    };
+}
+function finiteSkew(clockSkewMs) {
+    if (clockSkewMs === undefined || !Number.isFinite(clockSkewMs) || clockSkewMs < 0) {
+        return 0;
+    }
+    return clockSkewMs;
+}
+function websocketGrant(header) {
+    if (header === null) {
+        return undefined;
+    }
+    for (const part of header.split(',')) {
+        const protocol = part.trim();
+        if (protocol.startsWith('v1.')) {
+            return protocol;
+        }
+    }
+    return undefined;
+}
+function importHmacKey(secret) {
+    return Effect.tryPromise({
+        try: () => crypto.subtle.importKey('raw', textEncoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']),
+        catch: () => new GrantError({ reason: 'signature' }),
+    });
+}
+function encodeBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    let encoded = btoa(binary).replaceAll('+', '-').replaceAll('/', '_');
+    while (encoded.endsWith('=')) {
+        encoded = encoded.slice(0, -1);
+    }
+    return encoded;
+}
+function decodeBase64Url(value) {
+    if (value.length === 0 || value.length % 4 === 1 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+        return undefined;
+    }
+    const padded = value + '='.repeat((4 - (value.length % 4)) % 4);
+    const binary = atob(padded.replaceAll('-', '+').replaceAll('_', '/'));
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}