@stigmer/server 3.24.0 → 3.26.0

package/src/domain/workflowexecution/queries.ts

@@ -1,48 +1,159 @@
 /**
- * Shared full-scan load for the workflowexecution read surfaces (list,
- * listByWorkflow, getExecutionSummary, listPendingApprovals) — Go's
- * store.ListResources + proto.Unmarshal-continue loop, where malformed
- * rows are skipped rather than failing the read.
+ * The workflowexecution read surfaces' shared reads (list,
+ * listByWorkflow, getExecutionSummary, listPendingApprovals), all through
+ * the list index (list-index.ts beside this file; the store's contract in
+ * store/interface.ts) — the request's org or workflow key narrows in the
+ * store, newest created first. Malformed rows are skipped rather than
+ * failing the read, Go's proto.Unmarshal-continue loop.
+ *
+ * The two lists share one reader: the default order pages
+ * (pipeline/steps/list-page.ts), with the lane's filters and then the read
+ * scope on each batch; another sort field sorts the whole matching set and
+ * returns its first page_size entries with no token, because only the
+ * creation order is an index order.
  */
-import { fromBinary } from "@bufbuild/protobuf";
+import { create, fromBinary } from "@bufbuild/protobuf";
 
 import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import {
+  ExecutionSortField,
+  WorkflowExecutionListSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { WorkflowExecutionList } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
 import type { Logger } from "../../boot/logger.js";
-import { internalError } from "../../pipeline/errors.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ListReadScope } from "../../extensions/list-read-scope.js";
+import { restrictListByReadScope } from "../../extensions/list-read-scope.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import {
+  LIST_PAGE_MAX_SIZE,
+  listPageFingerprint,
+  readListPage,
+} from "../../pipeline/steps/list-page.js";
+import type { ListPageRequest } from "../../pipeline/steps/list-page.js";
 import type { Store } from "../../store/interface.js";
+import type { ListIndexQuery, ListIndexRow } from "../../store/list-index.js";
+import { applySortField } from "./execution-filter.js";
+import { workflowExecutionListIndex } from "./list-index.js";
+
+/** The keys the workflow-execution index declares. */
+export type WorkflowExecutionListKey = "workflow" | "workflow_instance";
+
+/** A stored row, or undefined (logged) when it does not decode. */
+export function decodeWorkflowExecution(
+  data: Uint8Array,
+  logger: Logger,
+): WorkflowExecution | undefined {
+  try {
+    return fromBinary(WorkflowExecutionSchema, data);
+  } catch (error) {
+    logger.warn("Failed to unmarshal workflow execution, skipping", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+}
 
 /**
- * Loads every workflow execution. The Internal message varies by caller in
- * Go (each handler wraps the same store error with its own text), so the
- * caller supplies it.
+ * Every workflow execution the query matches, newest created first. The
+ * Internal message varies by caller in Go (each handler wraps the same
+ * store error with its own text), so the caller supplies it.
  */
-export async function loadAllWorkflowExecutions(
+export async function loadWorkflowExecutions(
   store: Store,
   logger: Logger,
+  query: ListIndexQuery<WorkflowExecutionListKey>,
   internalMessage: string,
 ): Promise<WorkflowExecution[]> {
-  let rows: Uint8Array[];
+  let rows: ListIndexRow[];
   try {
-    rows = await store.listResources(ApiResourceKind.workflow_execution);
+    rows = await store.queryResources(workflowExecutionListIndex, query);
   } catch (error) {
     throw internalError(error, internalMessage);
   }
-
   const executions: WorkflowExecution[] = [];
-  for (const data of rows) {
-    let execution: WorkflowExecution;
-    try {
-      execution = fromBinary(WorkflowExecutionSchema, data);
-    } catch (error) {
-      logger.warn("Failed to unmarshal workflow execution, skipping", {
-        error: error instanceof Error ? error.message : String(error),
-      });
-      continue;
+  for (const row of rows) {
+    const execution = decodeWorkflowExecution(row.data, logger);
+    if (execution !== undefined) {
+      executions.push(execution);
     }
-    executions.push(execution);
   }
   return executions;
 }
+
+export interface WorkflowExecutionListRead {
+  readonly store: Store;
+  readonly logger: Logger;
+  readonly listReadScope: ListReadScope | undefined;
+  readonly identity: CallerIdentity;
+  readonly query: ListIndexQuery<WorkflowExecutionListKey>;
+  readonly request: ListPageRequest;
+  readonly sortField: ExecutionSortField;
+  readonly sortAscending: boolean;
+  /** The lane's filters beyond the indexed predicates. */
+  readonly keep: (execution: WorkflowExecution) => boolean;
+  /** The request's other fields, which its token is bound to. */
+  readonly fingerprint: Readonly<Record<string, unknown>>;
+}
+
+/** One list response: a page in the default order, or the whole set sorted by another field. */
+export async function readWorkflowExecutionList(
+  read: WorkflowExecutionListRead,
+): Promise<WorkflowExecutionList> {
+  const scope = (
+    executions: WorkflowExecution[],
+  ): Promise<WorkflowExecution[]> =>
+    restrictListByReadScope(
+      read.listReadScope,
+      read.identity,
+      ApiResourceKind.workflow_execution,
+      executions,
+      "",
+    );
+
+  if (read.sortField === ExecutionSortField.UNSPECIFIED) {
+    const page = await readListPage({
+      store: read.store,
+      declaration: workflowExecutionListIndex,
+      query: read.query,
+      request: read.request,
+      fingerprint: listPageFingerprint(read.fingerprint),
+      decode: (data) => decodeWorkflowExecution(data, read.logger),
+      keep: read.keep,
+      scope,
+      failure: "failed to list workflow executions",
+    });
+    return create(WorkflowExecutionListSchema, {
+      entries: page.entries,
+      nextPageToken: page.nextPageToken,
+      totalPages: page.nextPageToken === "" ? 1 : 0,
+    });
+  }
+
+  // Another sort field never issues a token, so none can be continued.
+  if (read.request.pageToken !== "") {
+    throw invalidArgumentError("invalid page_token");
+  }
+  if (read.request.pageSize < 0) {
+    throw invalidArgumentError("page_size must not be negative");
+  }
+  const executions = await scope(
+    (
+      await loadWorkflowExecutions(
+        read.store,
+        read.logger,
+        read.query,
+        "failed to list workflow executions",
+      )
+    ).filter(read.keep),
+  );
+  applySortField(executions, read.sortField, read.sortAscending);
+  const size = Math.min(read.request.pageSize, LIST_PAGE_MAX_SIZE);
+  return create(WorkflowExecutionListSchema, {
+    entries: size === 0 ? executions : executions.slice(0, size),
+    totalPages: 1,
+  });
+}

package/src/encryption/key-manager.ts

@@ -1,20 +1,26 @@
 /**
  * Named-key loader — ports pkg/encryption/keymanager.go.
  *
- * One convention for every 32-byte key the server holds (sub-project
- * DD-002): env var (Base64) → ~/.stigmer/<file> (raw bytes, 0600) →
- * auto-generate and persist. The loader is generalized over the env var
- * and file name so sibling key material (the runner-token signing key,
- * oss#535) rides the same ladder instead of growing a divergent loader.
+ * One convention for every key the server holds: env var (Base64) →
+ * ~/.stigmer/<file> (0600) → auto-generate and persist. The
+ * loader is generalized over the env var, the file name and a KeyCodec so
+ * sibling key material rides the same ladder instead of growing a
+ * divergent loader: the runner-token signing key (oss#535) and the
+ * encryption key are 32 raw bytes (RAW_32_BYTE_KEY); the platform-token
+ * signing key is an RSA private key (platformtoken/key-ring.ts). The codec
+ * says what a key IS — how an env value and a file decode, how one is
+ * generated and written — and nothing about the ladder, which stays one.
  *
- * Ladder semantics, exactly Go's:
+ * Ladder semantics, exactly Go's, for every codec:
  *   - An EXPLICITLY configured env key that is unusable (bad Base64, wrong
- *     length) is an ERROR, never a degrade — silently ignoring deliberate
- *     configuration would be worse than refusing to boot.
+ *     length, not the key type the codec holds) is an ERROR, never a
+ *     degrade — silently ignoring deliberate configuration would be worse
+ *     than refusing to boot.
  *   - A key file that fails its load checks (permissions other than 0600,
- *     wrong size) is never adopted; the ladder FALLS THROUGH to
- *     auto-generate, which overwrites the file's content — Go's shipped
- *     behavior (loadKeyFromFile error → generate → save), ported as-is.
+ *     content the codec does not accept) is never adopted; the ladder
+ *     FALLS THROUGH to auto-generate, which overwrites the file's content —
+ *     Go's shipped behavior (loadKeyFromFile error → generate → save),
+ *     ported as-is.
  *   - Auto-generation persists for future boots; a persist FAILURE is a
  *     stderr warning only — the key is still usable for this process.
  *
@@ -50,34 +56,81 @@ export interface KeyLoaderOptions {
 }
 
 /**
- * Go GetOrCreateNamedKey: env var → key file → auto-generate. Throws only
- * on unusable EXPLICIT configuration (bad env value) or when no key can be
- * produced at all.
+ * What one kind of key is, for the ladder. `fromEnv` receives the env
+ * value already strictly Base64-decoded and THROWS when the bytes are not
+ * a usable key (explicit configuration is never silently ignored);
+ * `fromFile` answers `undefined` for content it does not accept, so the
+ * ladder falls through exactly as it does for a wrong-sized raw key.
+ */
+export interface KeyCodec<Key> {
+  fromEnv(envVar: string, decoded: Buffer): Key;
+  fromFile(content: Buffer): Key | undefined;
+  generate(): Key;
+  toFile(key: Key): Buffer;
+}
+
+/** The 32 raw bytes the encryption and runner-token keys are. */
+export const RAW_32_BYTE_KEY: KeyCodec<Buffer> = {
+  fromEnv(envVar, decoded) {
+    if (decoded.length !== KEY_SIZE) {
+      throw new Error(
+        `${envVar} must be exactly 32 bytes (256 bits) when decoded, got ${decoded.length} bytes`,
+      );
+    }
+    return decoded;
+  },
+  fromFile(content) {
+    return content.length === KEY_SIZE ? content : undefined;
+  },
+  generate() {
+    return randomBytes(KEY_SIZE);
+  },
+  toFile(key) {
+    return key;
+  },
+};
+
+/**
+ * Go GetOrCreateNamedKey: env var → key file → auto-generate, for a 32-byte
+ * raw key. Throws only on unusable EXPLICIT configuration (bad env value)
+ * or when no key can be produced at all.
  */
 export function getOrCreateNamedKey(
   envVar: string,
   fileName: string,
   options: KeyLoaderOptions = {},
 ): Buffer {
+  return getOrCreateKey(RAW_32_BYTE_KEY, envVar, fileName, options);
+}
+
+/** The ladder over any codec: env var → key file → auto-generate. */
+export function getOrCreateKey<Key>(
+  codec: KeyCodec<Key>,
+  envVar: string,
+  fileName: string,
+  options: KeyLoaderOptions = {},
+): Key {
   const env = options.env ?? process.env;
 
-  // 1. Environment variable (highest priority) — Base64-encoded 32 bytes.
+  // 1. Environment variable (highest priority) — Base64-encoded.
   const envValue = env[envVar];
   if (envValue !== undefined && envValue !== "") {
-    return decodeEnvKey(envVar, envValue);
+    return codec.fromEnv(envVar, decodeEnvBase64(envVar, envValue));
   }
 
-  // 2. Local key file — raw 32 bytes, refused on insecure permissions.
+  // 2. Local key file — refused on insecure permissions or content the
+  //    codec does not accept.
   const keyPath = namedKeyFilePath(fileName, options);
-  const fromFile = loadKeyFromFile(keyPath);
+  const content = readKeyFile(keyPath);
+  const fromFile = content === undefined ? undefined : codec.fromFile(content);
   if (fromFile !== undefined) {
     return fromFile;
   }
 
   // 3. Auto-generate (local development); persist for future boots.
-  const key = randomBytes(KEY_SIZE);
+  const key = codec.generate();
   try {
-    saveKeyToFile(keyPath, key);
+    saveKeyToFile(keyPath, codec.toFile(key));
   } catch (error) {
     // Warn but don't fail — the key is still usable (Go's posture).
     process.stderr.write(
@@ -87,22 +140,17 @@ export function getOrCreateNamedKey(
   return key;
 }
 
-/** Strict Base64 decode + length check for an env-configured key. */
-function decodeEnvKey(envVar: string, value: string): Buffer {
-  const key = Buffer.from(value, "base64");
+/** Strict Base64 decode for an env-configured key. */
+function decodeEnvBase64(envVar: string, value: string): Buffer {
+  const decoded = Buffer.from(value, "base64");
   // Node's base64 decoder is lenient (skips invalid characters, accepts
   // missing padding) and never throws; Go's StdEncoding errors on any
   // non-canonical input. Round-tripping — Buffer always re-emits the
   // canonical padded form — restores Go's strictness.
-  if (key.toString("base64") !== value) {
+  if (decoded.toString("base64") !== value) {
     throw new Error(`invalid Base64 encoding in ${envVar}`);
   }
-  if (key.length !== KEY_SIZE) {
-    throw new Error(
-      `${envVar} must be exactly 32 bytes (256 bits) when decoded, got ${key.length} bytes`,
-    );
-  }
-  return key;
+  return decoded;
 }
 
 /** Path to a named key file under <home>/.stigmer. */
@@ -115,13 +163,13 @@ export function namedKeyFilePath(
 }
 
 /**
- * Reads raw key bytes, mirroring Go loadKeyFromFile: missing file →
- * undefined (fall through the ladder); present-but-wrong (insecure
- * permissions, wrong size) also falls through — exactly Go's behavior,
- * where any load error falls to auto-generate. The 0600 check is skipped
- * on Windows, where POSIX modes are not meaningful.
+ * Reads a key file's bytes, mirroring Go loadKeyFromFile: missing file →
+ * undefined (fall through the ladder); present with insecure permissions
+ * also falls through — exactly Go's behavior, where any load error falls
+ * to auto-generate. The 0600 check is skipped on Windows, where POSIX
+ * modes are not meaningful.
  */
-function loadKeyFromFile(keyPath: string): Buffer | undefined {
+function readKeyFile(keyPath: string): Buffer | undefined {
   let stat: fs.Stats;
   try {
     stat = fs.statSync(keyPath);
@@ -134,23 +182,18 @@ function loadKeyFromFile(keyPath: string): Buffer | undefined {
       return undefined;
     }
   }
-  let key: Buffer;
   try {
-    key = fs.readFileSync(keyPath);
+    return fs.readFileSync(keyPath);
   } catch {
     return undefined;
   }
-  if (key.length !== KEY_SIZE) {
-    return undefined;
-  }
-  return key;
 }
 
 /** Writes the key with secure permissions (dir 0700, file 0600). */
-function saveKeyToFile(keyPath: string, key: Buffer): void {
+function saveKeyToFile(keyPath: string, content: Buffer): void {
   fs.mkdirSync(path.dirname(keyPath), {
     recursive: true,
     mode: KEY_DIR_PERMISSIONS,
   });
-  fs.writeFileSync(keyPath, key, { mode: KEY_FILE_PERMISSIONS });
+  fs.writeFileSync(keyPath, content, { mode: KEY_FILE_PERMISSIONS });
 }

package/src/extensions/__tests__/extension-composition.test.ts

@@ -549,8 +549,9 @@ describe("extension composition (require-authentication posture)", () => {
     // composes its Authorizer, and with it the runner-subject verifier
     // between the API-key lane and the unit's own (runnerauth/
     // runner-subject-verifier.ts). A unit with its own Authorizer gets
-    // neither (runner-subject-composed.test.ts pins that chain).
-    expect(parsed.verifiers).toBe("apikey, runner, fake-verifier");
+    // neither (runner-subject-composed.test.ts pins that chain). The
+    // PlatformClient lane rides the posture itself, ahead of both.
+    expect(parsed.verifiers).toBe("apikey, platform-client, runner, fake-verifier");
   });
 
   it("a declared posture whose unit registers no verifier of its own is a boot throw naming the unit — the API-key lane alone cannot bootstrap", async () => {