@lostgradient/weft 0.2.0

package/dist/server/operations/worker-drain.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { shapeOperationFaultAsJson } from "../operation-fault.js";
+import { defineOperation } from "../operation-registry.js";
+import { invalidParamsFault } from "./operation-helpers.js";
+const drainReasonSchema = z.string().min(1).max(256).optional(), workerDrainInput = z.object({
+  workerId: z.string().min(1),
+  reason: drainReasonSchema
+}), workerDrainClearInput = z.object({
+  workerId: z.string().min(1)
+}), deploymentDrainInput = z.object({
+  deploymentName: z.string().min(1),
+  reason: drainReasonSchema
+}), deploymentDrainClearInput = z.object({
+  deploymentName: z.string().min(1)
+}), workerDrainResultSchema = z.object({
+  target: z.literal("worker"),
+  workerId: z.string(),
+  affectedWorkers: z.number(),
+  inFlight: z.number(),
+  health: z.enum(["active", "draining", "drained"])
+}), deploymentDrainResultSchema = z.object({
+  target: z.literal("deployment"),
+  deploymentName: z.string(),
+  affectedWorkers: z.number(),
+  inFlight: z.number(),
+  health: z.enum(["active", "draining", "drained"])
+}), workerDrainOutput = z.discriminatedUnion("target", [
+  workerDrainResultSchema,
+  deploymentDrainResultSchema
+]), adminAccess = {
+  kind: "scoped",
+  scopes: { kind: "anyOf", scopes: ["system:admin"] }
+};
+export function createDrainWorkerOperation(options) {
+  const registry = options?.workerRegistry, clock = options?.clock ?? Date.now;
+  return defineOperation({
+    name: "weft.workers.drain",
+    mcpExposable: !1,
+    summary: "Mark a connected worker as draining",
+    description: "Mark a connected worker as draining by `workerId` so the engine stops dispatching new tasks to it while in-flight tasks finish, with an optional `reason`. Used for graceful shutdown and rolling deploys; clear the marker with the worker-resume operation. Faults with NotFound when no worker with the given id is connected.",
+    destructive: !0,
+    tags: ["System"],
+    inputSchema: workerDrainInput,
+    outputSchema: workerDrainOutput,
+    access: adminAccess,
+    producibleFaults: ["NotFound"],
+    discoverable: !0,
+    transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+    unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+    invoke: async ({ input }) => {
+      if (registry === void 0)
+        throw discoveryOnlyError("weft.workers.drain");
+      const result = registry.markWorkerDraining(input.workerId, {
+        updatedAt: clock(),
+        ...input.reason !== void 0 ? { reason: input.reason } : {}
+      });
+      if (result === void 0)
+        throw workerNotFoundFault(input.workerId);
+      return result;
+    }
+  });
+}
+export function createClearWorkerDrainOperation(options) {
+  const registry = options?.workerRegistry;
+  return defineOperation({
+    name: "weft.workers.resume",
+    mcpExposable: !1,
+    summary: "Clear a connected worker drain marker",
+    destructive: !1,
+    tags: ["System"],
+    inputSchema: workerDrainClearInput,
+    outputSchema: workerDrainOutput,
+    access: adminAccess,
+    producibleFaults: ["NotFound"],
+    discoverable: !0,
+    transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+    unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+    invoke: async ({ input }) => {
+      if (registry === void 0)
+        throw discoveryOnlyError("weft.workers.resume");
+      const result = registry.clearWorkerDrain(input.workerId);
+      if (result === void 0)
+        throw workerNotFoundFault(input.workerId);
+      return result;
+    }
+  });
+}
+export function createDrainDeploymentOperation(options) {
+  const registry = options?.workerRegistry, clock = options?.clock ?? Date.now;
+  return defineOperation({
+    name: "weft.worker.deployments.drain",
+    mcpExposable: !1,
+    summary: "Mark a worker deployment as draining",
+    destructive: !0,
+    tags: ["System"],
+    inputSchema: deploymentDrainInput,
+    outputSchema: workerDrainOutput,
+    access: adminAccess,
+    discoverable: !0,
+    transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+    unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+    invoke: async ({ input }) => {
+      if (registry === void 0)
+        throw discoveryOnlyError("weft.worker.deployments.drain");
+      return registry.markDeploymentDraining(input.deploymentName, {
+        updatedAt: clock(),
+        ...input.reason !== void 0 ? { reason: input.reason } : {}
+      });
+    }
+  });
+}
+export function createClearDeploymentDrainOperation(options) {
+  const registry = options?.workerRegistry;
+  return defineOperation({
+    name: "weft.worker.deployments.resume",
+    mcpExposable: !1,
+    summary: "Clear a worker deployment drain marker",
+    destructive: !1,
+    tags: ["System"],
+    inputSchema: deploymentDrainClearInput,
+    outputSchema: workerDrainOutput,
+    access: adminAccess,
+    discoverable: !0,
+    transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+    unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+    invoke: async ({ input }) => {
+      if (registry === void 0)
+        throw discoveryOnlyError("weft.worker.deployments.resume");
+      return registry.clearDeploymentDrain(input.deploymentName);
+    }
+  });
+}
+export const drainWorkerOperation = createDrainWorkerOperation(), clearWorkerDrainOperation = createClearWorkerDrainOperation(), drainDeploymentOperation = createDrainDeploymentOperation(), clearDeploymentDrainOperation = createClearDeploymentDrainOperation();
+export function createDrainWorkerRestBinding() {
+  return createWorkerDrainRestBinding("POST", "weft.workers.drain");
+}
+export function createClearWorkerDrainRestBinding() {
+  return createWorkerDrainRestBinding("DELETE", "weft.workers.resume");
+}
+export function createDrainDeploymentRestBinding() {
+  return createDeploymentDrainRestBinding("POST", "weft.worker.deployments.drain");
+}
+export function createClearDeploymentDrainRestBinding() {
+  return createDeploymentDrainRestBinding("DELETE", "weft.worker.deployments.resume");
+}
+function createWorkerDrainRestBinding(method, operationName) {
+  return {
+    method,
+    path: "/v1/workers/:workerId/drain",
+    pathParamNames: ["workerId"],
+    operationName,
+    inputSources: {
+      workerId: { kind: "path", pathParam: "workerId" },
+      ...method === "POST" ? { reason: { kind: "body-field", bodyField: "reason" } } : {}
+    },
+    extractInput: async (request, pathParams) => ({
+      workerId: pathParams.workerId ?? "",
+      ...method === "POST" ? await readDrainBody(request) : {}
+    }),
+    success: { kind: "json", status: 200 },
+    shapeSuccess: shapeDrainSuccess,
+    shapeFault: shapeOperationFaultAsJson
+  };
+}
+function createDeploymentDrainRestBinding(method, operationName) {
+  return {
+    method,
+    path: "/v1/worker-deployments/:deploymentName/drain",
+    pathParamNames: ["deploymentName"],
+    operationName,
+    inputSources: {
+      deploymentName: { kind: "path", pathParam: "deploymentName" },
+      ...method === "POST" ? { reason: { kind: "body-field", bodyField: "reason" } } : {}
+    },
+    extractInput: async (request, pathParams) => ({
+      deploymentName: pathParams.deploymentName ?? "",
+      ...method === "POST" ? await readDrainBody(request) : {}
+    }),
+    success: { kind: "json", status: 200 },
+    shapeSuccess: shapeDrainSuccess,
+    shapeFault: shapeOperationFaultAsJson
+  };
+}
+function shapeDrainSuccess(output) {
+  return new Response(JSON.stringify(output), {
+    status: 200,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+async function readDrainBody(request) {
+  const text = await request.text();
+  if (text.trim().length === 0)
+    return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw invalidParamsFault("Drain request body must be valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    throw invalidParamsFault("Drain request body must be a JSON object");
+  const reason = parsed.reason;
+  return reason === void 0 ? {} : { reason };
+}
+function discoveryOnlyError(operationName) {
+  return Error(`${operationName} invoked from a discovery-only operation registry; no WorkerRegistry was wired in`);
+}
+function workerNotFoundFault(workerId) {
+  return {
+    code: "NotFound",
+    message: `Worker not found: ${workerId}`,
+    data: { resource: "worker", identifier: workerId }
+  };
+}

package/dist/server/operations/workflow-events-subscription.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+declare const workflowEventsSubscriptionInput: z.ZodObject<{
+    workflowId: z.ZodString;
+    selector: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        events: "events";
+        tokens: "tokens";
+    }>>>;
+    fromCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const workflowEventsSubscriptionEnvelope: z.ZodObject<{
+    subscriptionId: z.ZodString;
+    cursor: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowEventsSubscriptionInput = z.infer<typeof workflowEventsSubscriptionInput>;
+export type WorkflowEventsSubscriptionEnvelope = z.infer<typeof workflowEventsSubscriptionEnvelope>;
+/**
+ * Cataloged subscription operation for replay-plus-live workflow events.
+ * The WebSocket session owns the lifecycle primitive; this operation owns
+ * validation, authorization, and feed wiring.
+ *
+ * **Security model.** Subscriptions are capability grants for the lifetime
+ * of the WebSocket session: the catalog access policy is checked once at
+ * subscribe time, and once granted the subscription continues delivering
+ * events until the client unsubscribes, the socket closes, or the feed
+ * terminates. There is no per-event re-authorization in v1, so a token's
+ * scope must be revoked AT THE SOCKET LEVEL (close + reconnect) to stop
+ * event delivery — token revocation alone does not terminate active
+ * subscriptions. This is documented as a known v1 constraint; per-event
+ * filtering is a planned future refinement.
+ *
+ * Access is `scoped: { workflows:read }` (NOT optionalAuth, NOT public).
+ * Anonymous callers and authenticated callers without `workflows:read` are
+ * both denied. The earlier policies allowed unauthenticated clients to
+ * subscribe to arbitrary workflow event streams — a real exposure the
+ * security committee flagged. Operators running `serve({ engine })`
+ * without auth must add an authentication layer before exposing this
+ * endpoint to untrusted networks.
+ */
+export declare const workflowEventsSubscriptionOperation: import("../operation-catalog.ts").OperationDefinition<{
+    workflowId: string;
+    selector: "events" | "tokens";
+    fromCursor?: string | undefined;
+}, {
+    subscriptionId: string;
+    cursor: string;
+}>;
+export {};

package/dist/server/operations/workflow-events-subscription.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+const INITIAL_SUBSCRIPTION_CURSOR = "-1", workflowEventsSubscriptionInput = z.object({
+  workflowId: z.string().min(1),
+  selector: z.enum(["events", "tokens"]).optional().default("events"),
+  fromCursor: z.string().optional()
+}), workflowEventsSubscriptionEnvelope = z.object({
+  subscriptionId: z.string(),
+  cursor: z.string()
+});
+export const workflowEventsSubscriptionOperation = defineOperation({
+  name: "weft.workflows.events",
+  mcpExposable: !1,
+  kind: "subscription",
+  summary: "Subscribe to workflow events with replay-from-cursor",
+  destructive: !1,
+  tags: ["Events"],
+  inputSchema: workflowEventsSubscriptionInput,
+  outputSchema: workflowEventsSubscriptionEnvelope,
+  eventSchema: z.object({
+    kind: z.string(),
+    workflowId: z.string(),
+    selector: z.enum(["events", "tokens"]),
+    sequence: z.number(),
+    cursor: z.string(),
+    emittedAtMs: z.number(),
+    payload: z.unknown()
+  }),
+  access: {
+    kind: "scoped",
+    scopes: { kind: "anyOf", scopes: ["workflows:read"] }
+  },
+  discoverable: !0,
+  transports: { http: !1, jsonRpcHttp: !1, jsonRpcWebSocket: !0, jsonRpcStdio: !1 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    const feed = engine.feed, controller = new AbortController, startingCursor = input.fromCursor ?? INITIAL_SUBSCRIPTION_CURSOR, iterable = feed.subscribe({
+      workflowId: input.workflowId,
+      selector: input.selector,
+      ...input.fromCursor === void 0 ? {} : { fromCursor: input.fromCursor },
+      signal: controller.signal
+    });
+    return {
+      envelope: { subscriptionId: `sub_${crypto.randomUUID()}`, cursor: startingCursor },
+      iterable,
+      close: async () => {
+        controller.abort();
+      }
+    };
+  }
+});

package/dist/server/principal.d.ts

@@ -0,0 +1,176 @@
+/**
+ * AuthenticatedPrincipal construction and the Principal discriminated union.
+ *
+ * Principals are the transport-neutral representation of "who made this call."
+ * Every transport edge (REST, JSON-RPC HTTP, JSON-RPC WS upgrade, stdio
+ * admission) validates credentials and produces exactly one of these shapes
+ * before any operation pipeline runs.
+ *
+ * Credential *validation* (signature verification, expiry, revocation, format
+ * checks) is the transport edge's responsibility — these factories assume the
+ * inputs they receive describe a credential that has already been accepted.
+ *
+ * The discriminator string for API keys is `'api-key'` (kebab-case) to match
+ * the existing `AuthMethod` literal in `authentication.ts`. Keep them aligned;
+ * the bridge from `AuthResult` to `Principal` relies on byte-identical strings.
+ *
+ * See Track 8 design decisions 3 and 10.
+ */
+import { type AuthorizationScope } from './authorization-scope.ts';
+/**
+ * Raw JWT payload — intentionally loose; individual claim access is
+ * type-guarded at read sites. **Non-authoritative for authorization
+ * decisions.** Use `principal.subject` and `principal.scopes` (both
+ * derived and normalized at construction time) instead. The `claims`
+ * bag is preserved for debugging and pass-through.
+ *
+ * @example
+ * ```ts
+ * import { principalFromJwtClaims, type JwtClaims } from '@lostgradient/weft/mcp';
+ *
+ * const claims: JwtClaims = {
+ *   sub: 'user-123',
+ *   scope: 'workflows:read',
+ * };
+ * const principal = principalFromJwtClaims(claims);
+ * console.log(principal.subject);
+ * ```
+ */
+export type JwtClaims = Record<string, unknown>;
+/**
+ * An authenticated caller — JWT, API key, or mTLS. Carries the granted scope
+ * set and a `hasScope` accessor; downstream code should narrow to this shape
+ * via `isAuthenticated` before calling `hasScope`.
+ *
+ * The privileged `'stdio-local'` principal is for local stdio admission and
+ * carries the full local-admin scope set. It is exported for embedders that
+ * implement their own local admission gate; public transports should not mint
+ * it for remote callers.
+ *
+ * @example
+ * ```ts
+ * import { principalFromApiKey, type AuthenticatedPrincipal } from '@lostgradient/weft/mcp';
+ *
+ * const principal: AuthenticatedPrincipal = principalFromApiKey({
+ *   subject: 'local-tool',
+ *   scopes: ['workflows:read'],
+ * });
+ * console.log(principal.method);
+ * ```
+ */
+export type AuthenticatedPrincipal = {
+    readonly method: 'jwt' | 'api-key' | 'mtls' | 'stdio-local';
+    readonly scopes: ReadonlySet<AuthorizationScope>;
+    readonly claims: JwtClaims | undefined;
+    readonly subject: string | undefined;
+    hasScope(scope: AuthorizationScope): boolean;
+};
+/**
+ * An unauthenticated caller. Has no scopes and no `hasScope` method —
+ * deliberate, so callers MUST narrow via `isAuthenticated` before any
+ * scope-bearing access.
+ *
+ * @example
+ * ```ts
+ * import { anonymousPrincipal, type UnauthenticatedPrincipal } from '@lostgradient/weft/mcp';
+ *
+ * const principal: UnauthenticatedPrincipal = anonymousPrincipal();
+ * console.log(principal.method);
+ * ```
+ */
+export type UnauthenticatedPrincipal = {
+    readonly method: 'unauthenticated';
+};
+/**
+ * The full principal union used everywhere below the transport edge.
+ *
+ * @example
+ * ```ts
+ * import { anonymousPrincipal, type Principal } from '@lostgradient/weft/mcp';
+ *
+ * const principal: Principal = anonymousPrincipal();
+ * console.log(principal.method);
+ * ```
+ */
+export type Principal = AuthenticatedPrincipal | UnauthenticatedPrincipal;
+/**
+ * Build an `AuthenticatedPrincipal` from a JWT claims payload.
+ *
+ * @example
+ * ```ts
+ * import { principalFromJwtClaims } from '@lostgradient/weft/mcp';
+ *
+ * const principal = principalFromJwtClaims({
+ *   sub: 'user-123',
+ *   scope: 'workflows:read workflows:write',
+ * });
+ * console.log(principal.hasScope('workflows:read'));
+ * ```
+ */
+export declare function principalFromJwtClaims(claims: JwtClaims): AuthenticatedPrincipal;
+/**
+ * Build an `AuthenticatedPrincipal` from an API-key admission result.
+ *
+ * @example
+ * ```ts
+ * import { principalFromApiKey } from '@lostgradient/weft/mcp';
+ *
+ * const principal = principalFromApiKey({
+ *   subject: 'automation',
+ *   scopes: ['workflows:read'],
+ * });
+ * console.log(principal.subject);
+ * ```
+ */
+export declare function principalFromApiKey(options: {
+    subject: string;
+    scopes: ReadonlyArray<AuthorizationScope>;
+}): AuthenticatedPrincipal;
+/**
+ * Build an `AuthenticatedPrincipal` from an mTLS admission result.
+ *
+ * @example
+ * ```ts
+ * import { principalFromMutualTls } from '@lostgradient/weft/mcp';
+ *
+ * const principal = principalFromMutualTls({
+ *   subject: 'client-cert-subject',
+ *   scopes: ['system:read'],
+ * });
+ * console.log(principal.method);
+ * ```
+ */
+export declare function principalFromMutualTls(options: {
+    subject: string;
+    scopes: ReadonlyArray<AuthorizationScope>;
+}): AuthenticatedPrincipal;
+/**
+ * The single unauthenticated principal.
+ *
+ * @example
+ * ```ts
+ * import { anonymousPrincipal } from '@lostgradient/weft/mcp';
+ *
+ * const principal = anonymousPrincipal();
+ * console.log(principal.method);
+ * ```
+ */
+export declare function anonymousPrincipal(): UnauthenticatedPrincipal;
+/**
+ * Build the privileged `stdio-local` principal for the Phase 13
+ * runtime stdio subcommand. Admission is gated at the CLI boundary
+ * (`--startup-token <hex>` or `--allow-unauthenticated-local-admin`);
+ * once admitted, the session has every scope because it's running as
+ * a local process that can already invoke the binary directly.
+ *
+ * @example
+ * ```ts
+ * import { principalFromStdioLocal } from '@lostgradient/weft/mcp';
+ *
+ * const principal = principalFromStdioLocal();
+ * console.log(principal.hasScope('workflows:write'));
+ * ```
+ */
+export declare function principalFromStdioLocal(): AuthenticatedPrincipal;
+/** Type guard separating authenticated from unauthenticated principals. */
+export declare function isAuthenticated(principal: Principal): principal is AuthenticatedPrincipal;

package/dist/server/principal.js

@@ -0,0 +1,59 @@
+import {
+  AUTHORIZATION_SCOPES,
+  extractScopesFromClaims
+} from "./authorization-scope.js";
+export function principalFromJwtClaims(claims) {
+  const scopes = extractScopesFromClaims(claims), subject = typeof claims.sub === "string" ? claims.sub : void 0;
+  return {
+    method: "jwt",
+    scopes,
+    claims,
+    subject,
+    hasScope(scope) {
+      return scopes.has(scope);
+    }
+  };
+}
+export function principalFromApiKey(options) {
+  const scopes = new Set(options.scopes);
+  return {
+    method: "api-key",
+    scopes,
+    claims: void 0,
+    subject: options.subject,
+    hasScope(scope) {
+      return scopes.has(scope);
+    }
+  };
+}
+export function principalFromMutualTls(options) {
+  const scopes = new Set(options.scopes);
+  return {
+    method: "mtls",
+    scopes,
+    claims: void 0,
+    subject: options.subject,
+    hasScope(scope) {
+      return scopes.has(scope);
+    }
+  };
+}
+export function anonymousPrincipal() {
+  return ANONYMOUS;
+}
+export function principalFromStdioLocal() {
+  const scopes = new Set(AUTHORIZATION_SCOPES);
+  return {
+    method: "stdio-local",
+    scopes,
+    claims: void 0,
+    subject: "stdio-local",
+    hasScope(scope) {
+      return scopes.has(scope);
+    }
+  };
+}
+const ANONYMOUS = { method: "unauthenticated" };
+export function isAuthenticated(principal) {
+  return principal.method !== "unauthenticated";
+}