@stigmer/server 3.24.0 → 3.26.0

package/src/index.ts

@@ -59,6 +59,7 @@ export type {
 export type {
   ExtensionServiceRegistration,
   ResolvedExtensions,
+  ResolvedServiceRegistration,
   ServerExtension,
 } from "./extensions/registry.js";
 export type {
@@ -166,6 +167,60 @@ export type { AuthorizationQueryEngine } from "./extensions/authorization-querie
 export type { IdentityFederation } from "./extensions/identity-federation.js";
 export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
 export { identityIdForSubject } from "./domain/identityaccount/resolve.js";
+// The PlatformClient seams: the store PORT a composition drives the domain
+// through (drivers.platformClientStore; a driver throws
+// DuplicatePlatformClientError for a held id, slug or client_id) and its
+// vitest-free contract kit; the guest-token capability
+// (drivers.guestTokenMinting — the one token method only an edition that
+// hosts shared-agent pages serves); and the builder of the system-managed
+// client such an edition keeps per organization under the reserved slug,
+// so the tokens it signs for guests and schedule fires name a real client.
+export type { PlatformClientStore } from "./domain/platformclient/store.js";
+export { DuplicatePlatformClientError } from "./domain/platformclient/store.js";
+export type {
+  PlatformClientStoreContractCase,
+  PlatformClientStoreContractFixture,
+} from "./domain/platformclient/store-contract.js";
+export { platformClientStoreContract } from "./domain/platformclient/store-contract.js";
+export type { GuestTokenMinting } from "./extensions/guest-token-minting.js";
+export type { SystemManagedPlatformClientInput } from "./domain/platformclient/system-managed.js";
+export { newSystemManagedPlatformClient } from "./domain/platformclient/system-managed.js";
+export { SYSTEM_SHARE_CLIENT_SLUG } from "./domain/platformclient/constants.js";
+// The platform-token envelope and its key ring: the RS256 JWT every token
+// the server signs for itself rides. A composition supplies its ring
+// (drivers.platformTokenKeys, built from its PEMs), signs its own typed
+// lanes through the envelope — each with its own lifetime when it is not
+// the ring's default, the expiry handed back — and verifies them with the
+// same function and refusal copy open source's user-token lane uses.
+export type {
+  PlatformTokenClaimValue,
+  PlatformTokenRefusal,
+  PlatformTokenSigningOptions,
+  PlatformTokenVerification,
+  SignedPlatformToken,
+  VerifiedPlatformToken,
+} from "./platformtoken/envelope.js";
+export {
+  PLATFORM_TOKEN_ISSUER,
+  PLATFORM_TOKEN_REFUSAL_MESSAGES,
+  TOKEN_TYPE_CLAIM,
+  decodeVerifiedPlatformTokenPayload,
+  platformTokenRefusalError,
+  signPlatformToken,
+  stringClaim,
+  verifyPlatformToken,
+} from "./platformtoken/envelope.js";
+export type {
+  PlatformTokenKeyMaterial,
+  PlatformTokenKeyRing,
+  PlatformTokenSigner,
+  SigningPlatformTokenKeyRing,
+} from "./platformtoken/key-ring.js";
+export {
+  DEFAULT_PLATFORM_TOKEN_TTL_SECONDS,
+  canSign,
+  platformTokenKeyRingFromPem,
+} from "./platformtoken/key-ring.js";
 // The built-in authorizer's model seams: the kind
 // declarations (transcripts of the cloud's `.fga` files), the evaluator,
 // and the OpenFGA store-test kit — exported so the cloud's drift test
@@ -325,11 +380,20 @@ export { newResolveSlugStep } from "./pipeline/steps/slug.js";
 // The driver interfaces and the store-fault classes the ratified mapping
 // keys on (typed not-found → NotFound; anything else rethrows as an
 // infrastructure fault — the guidelines' instanceof idiom).
-export type { Store } from "./store/interface.js";
+export type { Store, StoreOpenOptions } from "./store/interface.js";
 export {
   AuditNotFoundError,
   ResourceNotFoundError,
 } from "./store/interface.js";
+// The list index's read shapes, which `Store.queryResources` speaks
+// (store/list-index.ts). Declaring an index stays internal: the list is
+// the composition root's (boot/list-indexes.ts), one per server.
+export type {
+  ListIndexCursor,
+  ListIndexDeclaration,
+  ListIndexQuery,
+  ListIndexRow,
+} from "./store/list-index.js";
 // The maintenance-surface row shape (20260830.04 Stage 1, ruling Q3):
 // what findResourcesRawOrderedAfter pages and what
 // replaceResourceDataIfUnchanged guards on — the secret-convergence

package/src/pipeline/interceptors/auth.ts

@@ -216,6 +216,33 @@ export function trustedLocalIdentityFor(operator: {
   };
 }
 
+/**
+ * The server acting for a principal it has authenticated some other way —
+ * the one construction of an `internal` caller outside the in-process
+ * transport's own stamp. Its consumer is the PlatformClient mint
+ * (domain/platformclient/mint.ts): the request is public and tokenless
+ * (so the chain stamped the trusted-local operator), the client proved
+ * itself with its secret, and the end-user account and role the mint
+ * creates must name the CLIENT as their actor, never the operator.
+ * `internal` because the server is the one acting — the create path's
+ * Authorize skips it, as for every server-composed request — and never
+ * reachable from the wire: no verifier produces it, and the serving
+ * chassis overwrites position 1 on every request.
+ */
+export function serverActingFor(principalId: string): CallerIdentity {
+  if (principalId === "") {
+    throw new Error(
+      "the server acts for a named principal — refusing to build an internal caller with none",
+    );
+  }
+  return {
+    identityId: principalId,
+    callerClass: "internal",
+    issuer: "",
+    rawToken: "",
+  };
+}
+
 /**
  * The serving chain's position-1 identity source: walks the composed
  * verifiers in order (OSS entries first, extension entries after, in

package/src/pipeline/steps/__tests__/list-page.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Pins the page loop every paged list lane shares (../list-page.ts),
+ * against a real store opened with the server's list indexes:
+ * `page_size` 0 reads the whole list with no token; a positive size walks
+ * every row in the store's order with no gap and no duplicate, the last
+ * page carrying no token (also when the rows end exactly on a page); a
+ * scope that refuses rows still fills pages and the cut resumes after the
+ * last row returned; a caller who may see nothing gets short pages bounded
+ * by the examine budget, each with a token, until the rows run out; a size
+ * above the contract's maximum is capped; and the token's refusals — a
+ * negative size, malformed text, a token issued for another request.
+ */
+import { create } from "@bufbuild/protobuf";
+import { ConnectError, Code } from "@connectrpc/connect";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { fromBinary } from "@bufbuild/protobuf";
+
+import { sessionListIndex } from "../../../domain/session/list-index.js";
+import { tempStore } from "../../../store/sqlite/__tests__/support.js";
+import type { TempStore } from "../../../store/sqlite/__tests__/support.js";
+import {
+  LIST_PAGE_MAX_SIZE,
+  examineBudgetOf,
+  listPageFingerprint,
+  readListPage,
+} from "../list-page.js";
+import type { ListPageParams } from "../list-page.js";
+
+let temp: TempStore;
+
+beforeEach(() => {
+  temp = tempStore();
+});
+
+afterEach(async () => {
+  await temp.cleanup();
+});
+
+async function seed(count: number): Promise<string[]> {
+  const ids: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const id = `ses_${String(i).padStart(4, "0")}`;
+    ids.push(id);
+    await temp.store.saveResource(
+      ApiResourceKind.session,
+      id,
+      SessionSchema,
+      create(SessionSchema, {
+        metadata: { id, org: "acme" },
+        status: {
+          audit: {
+            specAudit: { createdAt: { seconds: BigInt(1_000 + i), nanos: 0 } },
+          },
+        },
+      }),
+    );
+  }
+  // Newest first: the highest creation instant first.
+  return ids.reverse();
+}
+
+function params(
+  pageSize: number,
+  pageToken: string,
+  scope: (rows: Session[]) => Session[] = (rows) => rows,
+): ListPageParams<Session, "agent_instance" | "channel"> {
+  return {
+    store: temp.store,
+    declaration: sessionListIndex,
+    query: { org: "acme" },
+    request: { pageSize, pageToken },
+    fingerprint: listPageFingerprint({ lane: "test", org: "acme" }),
+    decode: (data) => fromBinary(SessionSchema, data),
+    scope: (rows) => Promise.resolve(scope(rows)),
+    failure: "failed to list sessions",
+  };
+}
+
+async function walk(
+  pageSize: number,
+  scope?: (rows: Session[]) => Session[],
+): Promise<{ ids: string[]; pages: number }> {
+  const ids: string[] = [];
+  let token = "";
+  let pages = 0;
+  do {
+    const page = await readListPage(params(pageSize, token, scope));
+    ids.push(...page.entries.map((s) => s.metadata!.id));
+    token = page.nextPageToken;
+    pages += 1;
+  } while (token !== "");
+  return { ids, pages };
+}
+
+async function refusal(promise: Promise<unknown>): Promise<ConnectError> {
+  try {
+    await promise;
+  } catch (error) {
+    if (error instanceof ConnectError) {
+      return error;
+    }
+    throw error;
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("readListPage", () => {
+  it("reads the whole list with no token at page_size 0", async () => {
+    const all = await seed(7);
+    const page = await readListPage(params(0, ""));
+    expect(page.entries.map((s) => s.metadata!.id)).toEqual(all);
+    expect(page.nextPageToken).toBe("");
+  });
+
+  it("walks every row with no gap and no duplicate, the last page without a token", async () => {
+    const all = await seed(7);
+    const { ids, pages } = await walk(3);
+    expect(ids).toEqual(all);
+    expect(pages).toBe(3);
+  });
+
+  it("issues no token when the rows end exactly on a page", async () => {
+    const all = await seed(6);
+    const { ids, pages } = await walk(3);
+    expect(ids).toEqual(all);
+    expect(pages).toBe(2);
+  });
+
+  it("fills pages around rows the scope refuses and resumes after the last row returned", async () => {
+    const all = await seed(12);
+    const refused = new Set(["ses_0010", "ses_0007", "ses_0006", "ses_0001"]);
+    const scope = (rows: Session[]) =>
+      rows.filter((s) => !refused.has(s.metadata!.id));
+    const first = await readListPage(params(3, "", scope));
+    expect(first.entries).toHaveLength(3);
+    const { ids } = await walk(3, scope);
+    expect(ids).toEqual(all.filter((id) => !refused.has(id)));
+  });
+
+  it("bounds what a caller who may see nothing examines, with a token until the rows run out", async () => {
+    await seed(250);
+    const noneVisible = () => [];
+    const first = await readListPage(params(20, "", noneVisible));
+    expect(first.entries).toEqual([]);
+    expect(first.nextPageToken).not.toBe("");
+    expect(examineBudgetOf(20)).toBe(100);
+    const { ids, pages } = await walk(20, noneVisible);
+    expect(ids).toEqual([]);
+    expect(pages).toBe(3);
+  });
+
+  it("caps a page at the contract's maximum", async () => {
+    await seed(LIST_PAGE_MAX_SIZE + 5);
+    const page = await readListPage(params(1_000, ""));
+    expect(page.entries).toHaveLength(LIST_PAGE_MAX_SIZE);
+    expect(page.nextPageToken).not.toBe("");
+  });
+
+  it("refuses a negative size, a malformed token and a token issued for another request", async () => {
+    await seed(4);
+    expect((await refusal(readListPage(params(-1, "")))).code).toBe(
+      Code.InvalidArgument,
+    );
+    const bad = await refusal(readListPage(params(2, "not a token")));
+    expect([bad.code, bad.rawMessage]).toEqual([
+      Code.InvalidArgument,
+      "invalid page_token",
+    ]);
+
+    const token = (await readListPage(params(2, ""))).nextPageToken;
+    const other = await refusal(
+      readListPage({
+        ...params(2, token),
+        fingerprint: listPageFingerprint({ lane: "test", org: "other" }),
+      }),
+    );
+    expect([other.code, other.rawMessage]).toEqual([
+      Code.InvalidArgument,
+      "page_token was issued for a different request",
+    ]);
+  });
+});

package/src/pipeline/steps/__tests__/references.test.ts

@@ -39,6 +39,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { reference_kind } from "@stigmer/protos/ai/stigmer/commons/apiresource/field_options_pb";
 import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 
 import type { Store } from "../../../store/interface.js";
 import { SqliteStore } from "../../../store/sqlite/store.js";
@@ -97,6 +98,7 @@ const SCHEMAS_UNDER_THE_RULE: ReadonlyArray<DescMessage> = [
   AgentExecutionSchema,
   WorkflowExecutionSchema,
   ExecutionContextSchema,
+  PlatformClientSchema,
   AgentCallTaskConfigSchema,
 ];
 

package/src/pipeline/steps/build-update-state.ts

@@ -115,9 +115,12 @@ function copyStatusFromExisting(
 /**
  * Go updateAuditFieldsReflect: spec_audit keeps the existing creation
  * identity with a fresh update stamp; status_audit is fully current (the
- * status was rebuilt); both carry event "updated".
+ * status was rebuilt); both carry event "updated". Exported for the one
+ * write that changes a stored resource outside this step — a
+ * PlatformClient secret rotation (domain/platformclient/steps.ts) — so an
+ * update's audit has one shape whichever step writes it.
  */
-function updateAuditFields(
+export function updateAuditFields(
   schema: DescMessage,
   resource: Message,
   existing: Message,

package/src/pipeline/steps/list-page.ts

@@ -0,0 +1,284 @@
+/**
+ * One page of a list lane read through the list index — the one
+ * implementation of the page loop every paged lane calls, so the rules
+ * below hold everywhere by construction:
+ *
+ * - The store narrows by the request's own predicates (organization, key,
+ *   creation window) and orders newest first (store/list-index.ts). The
+ *   lane's per-row filter runs on each batch, then the read scope, which
+ *   stays the last per-row predicate (extensions/list-read-scope.ts);
+ *   neither reorders, so a page is in the store's order.
+ * - `page_size` 0 reads every matching row and returns no token, the
+ *   behaviour every list lane had before it paged; a positive size is
+ *   capped at `LIST_PAGE_MAX_SIZE`.
+ * - A page fills batch by batch until it is full, the rows run out, or
+ *   `examineBudgetOf(size)` rows have been examined. A caller who may see
+ *   few of the organization's rows gets a short page, possibly empty, with
+ *   a token (the timeline's cursor contract, agentchannel/v1
+ *   conversation_io.proto), never an unbounded walk.
+ * - The token's cursor is the last row RETURNED when the page was cut,
+ *   else the last row EXAMINED, so no row is skipped and no refused row is
+ *   read twice. The token is opaque and versioned, carries a fingerprint
+ *   of the request's other fields (a mismatch is refused), and carries no
+ *   authority: every page re-runs the scope.
+ *
+ * Proven by __tests__/list-page.test.ts (the loop, the budget, the cut,
+ * the token) and end-to-end by the paging arms of the conformance suites.
+ */
+import { createHash } from "node:crypto";
+
+import type { Store } from "../../store/interface.js";
+import type {
+  ListIndexCursor,
+  ListIndexDeclaration,
+  ListIndexQuery,
+  ListIndexRow,
+} from "../../store/list-index.js";
+import { internalError, invalidArgumentError } from "../errors.js";
+
+/** The most entries one page returns, the contract's word on every paged request. */
+export const LIST_PAGE_MAX_SIZE = 100;
+
+/**
+ * The most rows one request examines for a page of `size`: five pages'
+ * worth, at least 100, at most 500. It bounds what one request asks of a
+ * composed read scope (on the hosted edition one authorization key per
+ * row, 50 per round trip) when the caller can see few of the rows.
+ */
+export function examineBudgetOf(size: number): number {
+  return Math.min(500, Math.max(100, size * 5));
+}
+
+/** The request fields every paged lane carries. */
+export interface ListPageRequest {
+  readonly pageSize: number;
+  readonly pageToken: string;
+}
+
+export interface ListPageParams<T, K extends string> {
+  readonly store: Store;
+  readonly declaration: ListIndexDeclaration<K>;
+  /** The request's own predicates, pushed into the store's indexed read. */
+  readonly query: Omit<ListIndexQuery<K>, "after" | "limit">;
+  readonly request: ListPageRequest;
+  /**
+   * The request's other fields, as text: a token is valid only for the
+   * request it was issued to.
+   */
+  readonly fingerprint: string;
+  /** Decodes a row; undefined skips it (the lane logs, as it always has). */
+  readonly decode: (data: Uint8Array) => T | undefined;
+  /** The lane's per-row filter beyond the indexed predicates. */
+  readonly keep?: (row: T) => boolean;
+  /** The read scope, bound by the lane to its caller and kind. */
+  readonly scope: (rows: T[]) => Promise<T[]>;
+  /** The failure copy for a store fault. */
+  readonly failure: string;
+}
+
+export interface ListPage<T> {
+  readonly entries: T[];
+  /** "" when the list is complete. */
+  readonly nextPageToken: string;
+}
+
+/** Reads one page (or, at `page_size` 0, the whole list) through the list index. */
+export async function readListPage<T, K extends string>(
+  params: ListPageParams<T, K>,
+): Promise<ListPage<T>> {
+  const { request } = params;
+  if (request.pageSize < 0) {
+    throw invalidArgumentError("page_size must not be negative");
+  }
+  let after =
+    request.pageToken === ""
+      ? undefined
+      : decodeListPageToken(request.pageToken, params.fingerprint).cursor;
+
+  if (request.pageSize === 0) {
+    const rows = await queryOrFail(params, after, undefined);
+    return {
+      entries: await admit(params, rows).then((a) => a.map((e) => e.row)),
+      nextPageToken: "",
+    };
+  }
+
+  const size = Math.min(request.pageSize, LIST_PAGE_MAX_SIZE);
+  const budget = examineBudgetOf(size);
+  const kept: Array<Admitted<T>> = [];
+  let examined = 0;
+  for (;;) {
+    // One row past the batch is read only to learn whether more follow,
+    // so a list that ends exactly on a page carries no token (and no
+    // empty page behind it); the next batch reads that row again.
+    const batchSize = Math.min(size, budget - examined);
+    const read = await queryOrFail(params, after, batchSize + 1);
+    const more = read.length > batchSize;
+    const rows = more ? read.slice(0, batchSize) : read;
+    examined += rows.length;
+    kept.push(...(await admit(params, rows)));
+    const last = rows[rows.length - 1];
+    if (last !== undefined) {
+      after = last.cursor;
+    }
+
+    if (kept.length >= size) {
+      const page = kept.slice(0, size);
+      const exhausted = !more && kept.length === size;
+      return {
+        entries: page.map((e) => e.row),
+        nextPageToken: exhausted
+          ? ""
+          : encodeListPageToken(
+              page[page.length - 1]!.cursor,
+              params.fingerprint,
+            ),
+      };
+    }
+    if (!more) {
+      return { entries: kept.map((e) => e.row), nextPageToken: "" };
+    }
+    if (examined >= budget) {
+      return {
+        entries: kept.map((e) => e.row),
+        nextPageToken: encodeListPageToken(after!, params.fingerprint),
+      };
+    }
+  }
+}
+
+interface Admitted<T> {
+  readonly row: T;
+  readonly cursor: ListIndexCursor;
+}
+
+async function queryOrFail<T, K extends string>(
+  params: ListPageParams<T, K>,
+  after: ListIndexCursor | undefined,
+  limit: number | undefined,
+): Promise<ListIndexRow[]> {
+  try {
+    return await params.store.queryResources(params.declaration, {
+      ...params.query,
+      ...(after === undefined ? {} : { after }),
+      ...(limit === undefined ? {} : { limit }),
+    });
+  } catch (error) {
+    throw internalError(error, params.failure);
+  }
+}
+
+/** A batch through the lane's filter and the scope, each row keeping its cursor. */
+async function admit<T, K extends string>(
+  params: ListPageParams<T, K>,
+  rows: ReadonlyArray<ListIndexRow>,
+): Promise<Array<Admitted<T>>> {
+  const decoded: Array<Admitted<T>> = [];
+  for (const row of rows) {
+    const value = params.decode(row.data);
+    if (
+      value !== undefined &&
+      (params.keep === undefined || params.keep(value))
+    ) {
+      decoded.push({ row: value, cursor: row.cursor });
+    }
+  }
+  if (decoded.length === 0) {
+    return [];
+  }
+  const allowed = new Set(await params.scope(decoded.map((d) => d.row)));
+  return decoded.filter((d) => allowed.has(d.row));
+}
+
+// =============================================================================
+// The token
+// =============================================================================
+
+const TOKEN_VERSION = 1;
+
+/**
+ * The position a token carries: the list index's cursor, plus, for a lane
+ * whose entries are finer than rows (the approvals of one execution), the
+ * entry's position within its row.
+ */
+export interface ListPageTokenCursor {
+  readonly cursor: ListIndexCursor;
+  readonly position?: number;
+}
+
+function fingerprintHash(fingerprint: string): string {
+  return createHash("sha256")
+    .update(fingerprint)
+    .digest("base64url")
+    .slice(0, 16);
+}
+
+/** An opaque, versioned token for the position after `cursor`. */
+export function encodeListPageToken(
+  cursor: ListIndexCursor,
+  fingerprint: string,
+  position?: number,
+): string {
+  const body = {
+    v: TOKEN_VERSION,
+    c: cursor.createdAt,
+    i: cursor.id,
+    f: fingerprintHash(fingerprint),
+    ...(position === undefined ? {} : { p: position }),
+  };
+  return Buffer.from(JSON.stringify(body)).toString("base64url");
+}
+
+/**
+ * The position a token carries, refused as `invalid page_token` (the copy
+ * every paged lane already answers with) when it is malformed, of a
+ * version this server never issued, or issued for another request.
+ */
+export function decodeListPageToken(
+  token: string,
+  fingerprint: string,
+): ListPageTokenCursor {
+  let body: unknown;
+  try {
+    const bytes = Buffer.from(token, "base64url");
+    if (bytes.toString("base64url") !== token) {
+      throw new Error("not canonical base64url");
+    }
+    body = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw invalidArgumentError("invalid page_token");
+  }
+  if (
+    typeof body !== "object" ||
+    body === null ||
+    (body as { v?: unknown }).v !== TOKEN_VERSION ||
+    typeof (body as { c?: unknown }).c !== "string" ||
+    typeof (body as { i?: unknown }).i !== "string" ||
+    typeof (body as { f?: unknown }).f !== "string"
+  ) {
+    throw invalidArgumentError("invalid page_token");
+  }
+  const parsed = body as { c: string; i: string; f: string; p?: unknown };
+  if (parsed.f !== fingerprintHash(fingerprint)) {
+    throw invalidArgumentError("page_token was issued for a different request");
+  }
+  if (
+    parsed.p !== undefined &&
+    !(Number.isSafeInteger(parsed.p) && (parsed.p as number) >= 0)
+  ) {
+    throw invalidArgumentError("invalid page_token");
+  }
+  return {
+    cursor: { createdAt: parsed.c, id: parsed.i },
+    ...(parsed.p === undefined ? {} : { position: parsed.p as number }),
+  };
+}
+
+/** A request's other fields as the text its token is bound to. */
+export function listPageFingerprint(
+  fields: Readonly<Record<string, unknown>>,
+): string {
+  return JSON.stringify(fields, (_key, value: unknown) =>
+    typeof value === "bigint" ? value.toString() : value,
+  );
+}