@stigmer/server 3.32.0 → 3.34.0

package/src/extensions/gate-slots.ts

@@ -43,6 +43,16 @@
  * resource, and a team member who is not one of the organization's
  * viewers. Never on `bootstrapPolicy`, the platform's structural lane.
  *
+ * The ninth, `org-create:pre-side-effect-gate`: the organization create
+ * chain after its last pure step (CopySlugToId) and before Persist, the
+ * position the session chain's slot holds. It exists for a refusal that
+ * must leave nothing behind: `org-create:post-persist` runs after the row
+ * is written, so a limit enforced there would leave the organization it
+ * refused. The Cloud refuses a platform-managed organization its
+ * integrator's plan does not admit; a licensed deployment's organization
+ * limit belongs here too. `apply` delegates to create on its create arm,
+ * so the slot fires there as well.
+ *
  * Two enforcement layers, deliberately redundant, both derived from the
  * ONE literal tuple below (lockstep by construction):
  *   - GateSlotName (compile time): the union of declared slot literals.
@@ -81,6 +91,7 @@ export const GATE_SLOT_NAMES = [
   "sandbox-acquisition:gate",
   "identity-account-provision:post-persist",
   "iam-policy-create:pre-side-effect-gate",
+  "org-create:pre-side-effect-gate",
 ] as const;
 
 /** The declared slot-name union — a registration outside it fails tsc. */

package/src/identity/__tests__/credential-use.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Pins the credential last-use rule (credential-use.ts):
+ *   - staleness is measured against the stored stamp, a never-used
+ *     credential is stale, and exactly one resolution is stale again;
+ *   - the stamp only moves forward, and a write bumps the status audit's
+ *     updated_at + event while keeping who created the slot;
+ *   - recordCredentialUse writes only when stale, treats a row deleted
+ *     meanwhile as nothing to record, and logs any other failure without
+ *     throwing.
+ */
+import { create } from "@bufbuild/protobuf";
+import { timestampDate, timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceAuditActorSchema,
+  ApiResourceAuditInfoSchema,
+  ApiResourceAuditSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+
+import { createLogger } from "../../boot/logger.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import {
+  LAST_USED_RESOLUTION_MS,
+  lastUseIsStale,
+  recordCredentialUse,
+  stampLastUsed,
+  type CredentialUseStatus,
+} from "../credential-use.js";
+
+const NOW = new Date("2026-09-28T12:00:00Z");
+
+function ago(ms: number): Date {
+  return new Date(NOW.getTime() - ms);
+}
+
+function capturingLogger(): {
+  lines: string[];
+  logger: ReturnType<typeof createLogger>;
+} {
+  const lines: string[] = [];
+  return {
+    lines,
+    logger: createLogger({
+      level: "debug",
+      pretty: false,
+      write: (line) => lines.push(line),
+    }),
+  };
+}
+
+describe("lastUseIsStale", () => {
+  it("is stale for a credential never used", () => {
+    expect(lastUseIsStale(undefined, NOW)).toBe(true);
+  });
+
+  it("is fresh inside one resolution and stale from exactly one resolution on", () => {
+    const justInside = timestampFromDate(ago(LAST_USED_RESOLUTION_MS - 1));
+    const exactly = timestampFromDate(ago(LAST_USED_RESOLUTION_MS));
+    expect(lastUseIsStale(justInside, NOW)).toBe(false);
+    expect(lastUseIsStale(exactly, NOW)).toBe(true);
+  });
+
+  it("is fresh for a stamp ahead of this replica's clock", () => {
+    expect(lastUseIsStale(timestampFromDate(new Date(NOW.getTime() + 5_000)), NOW)).toBe(false);
+  });
+});
+
+describe("stampLastUsed", () => {
+  it("stamps a never-used status and bumps the status audit", () => {
+    const status: CredentialUseStatus = {};
+    expect(stampLastUsed(status, NOW)).toBe(true);
+    expect(timestampDate(status.lastUsedAt!)).toEqual(NOW);
+    expect(status.audit?.statusAudit?.event).toBe("updated");
+    expect(status.audit?.statusAudit?.updatedAt).toBeDefined();
+  });
+
+  it("keeps who created the status-audit slot and never touches the spec audit", () => {
+    const createdBy = create(ApiResourceAuditActorSchema, { id: "ida_creator" });
+    const createdAt = timestampFromDate(ago(86_400_000));
+    const specAudit = create(ApiResourceAuditInfoSchema, { createdBy, createdAt, event: "created" });
+    const priorSlot = create(ApiResourceAuditInfoSchema, { createdBy, createdAt, event: "created" });
+    const status: CredentialUseStatus = {
+      audit: create(ApiResourceAuditSchema, { specAudit, statusAudit: priorSlot }),
+    };
+
+    stampLastUsed(status, NOW);
+
+    expect(status.audit?.statusAudit?.createdBy?.id).toBe("ida_creator");
+    expect(status.audit?.statusAudit?.createdAt).toEqual(createdAt);
+    expect(status.audit?.statusAudit?.event).toBe("updated");
+    expect(status.audit?.specAudit).toBe(specAudit);
+    expect(priorSlot.event, "a new slot is set, the old one is not mutated").toBe("created");
+  });
+
+  it("only moves forward: a stamp at or after the use is kept, audit untouched", () => {
+    const later = timestampFromDate(new Date(NOW.getTime() + 1_000));
+    const status: CredentialUseStatus = { lastUsedAt: later };
+    expect(stampLastUsed(status, NOW)).toBe(false);
+    expect(status.lastUsedAt).toBe(later);
+    expect(status.audit).toBeUndefined();
+
+    const same = timestampFromDate(NOW);
+    const atSameInstant: CredentialUseStatus = { lastUsedAt: same };
+    expect(stampLastUsed(atSameInstant, NOW)).toBe(false);
+  });
+});
+
+describe("recordCredentialUse", () => {
+  function use(overrides: {
+    lastUsedAt?: Date;
+    write: (stamp: (status: CredentialUseStatus) => void) => Promise<unknown>;
+    logger?: ReturnType<typeof createLogger>;
+  }) {
+    return {
+      credential: "api key",
+      id: "key_1",
+      lastUsedAt:
+        overrides.lastUsedAt === undefined ? undefined : timestampFromDate(overrides.lastUsedAt),
+      now: NOW,
+      logger: overrides.logger ?? capturingLogger().logger,
+      write: overrides.write,
+    };
+  }
+
+  it("writes the stamp through the kind's atomic write when stale", async () => {
+    const row: CredentialUseStatus = {};
+    let writes = 0;
+    await recordCredentialUse(
+      use({
+        write: async (stamp) => {
+          writes += 1;
+          stamp(row);
+        },
+      }),
+    );
+    expect(writes).toBe(1);
+    expect(timestampDate(row.lastUsedAt!)).toEqual(NOW);
+  });
+
+  it("does not write inside the resolution", async () => {
+    let writes = 0;
+    await recordCredentialUse(
+      use({
+        lastUsedAt: ago(LAST_USED_RESOLUTION_MS / 2),
+        write: async () => {
+          writes += 1;
+        },
+      }),
+    );
+    expect(writes).toBe(0);
+  });
+
+  it("treats a row deleted meanwhile as nothing to record, silently", async () => {
+    const { lines, logger } = capturingLogger();
+    await recordCredentialUse(
+      use({
+        logger,
+        write: async () => {
+          throw new ResourceNotFoundError("api_key/key_1");
+        },
+      }),
+    );
+    expect(lines).toEqual([]);
+  });
+
+  it("logs any other failure with the credential id and never throws", async () => {
+    const { lines, logger } = capturingLogger();
+    await expect(
+      recordCredentialUse(
+        use({
+          logger,
+          write: async () => {
+            throw new Error("database unavailable");
+          },
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    expect(lines).toHaveLength(1);
+    const entry = JSON.parse(lines[0]!) as Record<string, unknown>;
+    expect(entry.level).toBe("warn");
+    expect(entry.credential).toBe("api key");
+    expect(entry.id).toBe("key_1");
+    expect(entry.error).toBe("database unavailable");
+  });
+});

package/src/identity/credential-use.ts

@@ -0,0 +1,130 @@
+/**
+ * When a credential was last used: the one rule the two credential kinds
+ * that carry `status.last_used_at` share. An API key is stamped by the
+ * identity verifier that accepts it (domain/apikey/verifier.ts), a
+ * PlatformClient by a successful mint (domain/platformclient/mint.ts). It
+ * lives here, beside the other infrastructure the credential lanes share,
+ * because neither domain owns the other (stigmer/stigmer#1255).
+ *
+ * The stamp is status the platform writes on its own, so it follows the
+ * house rule for such writes: an atomic read-modify-write on the row
+ * (`Store.updateResource`; the PlatformClient port's `modifyById`), the
+ * narrow status-audit bump (pipeline/steps/defaults.ts), and best-effort
+ * with a loud log, as `stampLastFireAt` records a schedule's manual fire
+ * (domain/schedule/trigger.ts). Never a load-then-save of the whole row:
+ * the credential's own update chains replace the row whole, and a stale
+ * copy written back by a stamp would undo them (a rotated PlatformClient
+ * secret would work again).
+ *
+ * The resolution keeps a credential that rides every request from costing
+ * a write per request, and it needs no state: the caller already holds the
+ * row it just verified, so "stamped less than a resolution ago" is one
+ * comparison with the stored value, the same answer on every replica and
+ * after every restart. Callers that pass the check at the same instant
+ * each write once; every write only moves the stamp forward, so the extra
+ * writes change nothing.
+ */
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { timestampDate, timestampFromDate } from "@bufbuild/protobuf/wkt";
+
+import type { ApiResourceAudit } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+
+import type { Logger } from "../boot/logger.js";
+import { bumpStatusAudit } from "../pipeline/steps/defaults.js";
+import { ResourceNotFoundError } from "../store/interface.js";
+
+/**
+ * How stale a stored last use may be before a new use records again: one
+ * minute. Fresh enough that the console's "Used 3m" is true to the minute;
+ * coarse enough that a key behind every request costs at most one write a
+ * minute per replica. Both fields' proto comments state it.
+ */
+export const LAST_USED_RESOLUTION_MS = 60_000;
+
+/** The status shape both credential kinds share. */
+export interface CredentialUseStatus {
+  lastUsedAt?: Timestamp;
+  audit?: ApiResourceAudit;
+}
+
+/** True when a use at `now` should be recorded over the stored `lastUsedAt`. */
+export function lastUseIsStale(
+  lastUsedAt: Timestamp | undefined,
+  now: Date,
+): boolean {
+  return (
+    lastUsedAt === undefined ||
+    now.getTime() - timestampDate(lastUsedAt).getTime() >=
+      LAST_USED_RESOLUTION_MS
+  );
+}
+
+/**
+ * Records a use at `usedAt`, forward only: a stored stamp at or after it (a
+ * replica whose clock runs ahead, a racing caller that wrote first) is
+ * kept, and the audit is left alone. Returns whether it wrote. Synchronous,
+ * because it runs inside an atomic write's `modify`.
+ */
+export function stampLastUsed(
+  status: CredentialUseStatus,
+  usedAt: Date,
+): boolean {
+  const stored = status.lastUsedAt;
+  if (
+    stored !== undefined &&
+    timestampDate(stored).getTime() >= usedAt.getTime()
+  ) {
+    return false;
+  }
+  status.lastUsedAt = timestampFromDate(usedAt);
+  bumpStatusAudit(status);
+  return true;
+}
+
+export interface CredentialUse {
+  /** What the log calls the credential ("api key", "platform client"). */
+  readonly credential: string;
+  /** The credential's resource id: logged, never the secret. */
+  readonly id: string;
+  /** The stored stamp, as the caller read the row it just verified. */
+  readonly lastUsedAt: Timestamp | undefined;
+  readonly now: Date;
+  readonly logger: Logger;
+  /**
+   * The kind's atomic write: applies `stamp` to the row's status (created
+   * when absent) inside one read-modify-write. A row deleted since the
+   * caller read it is a typed not-found or a write that finds nothing.
+   */
+  readonly write: (
+    stamp: (status: CredentialUseStatus) => void,
+  ) => Promise<unknown>;
+}
+
+/**
+ * Records the use when the stored stamp is stale. Never throws: the
+ * credential already did its job, and a bookkeeping failure must not turn
+ * an accepted request or a minted token into an error. A row deleted
+ * meanwhile has nothing to record; any other failure is logged.
+ */
+export async function recordCredentialUse(use: CredentialUse): Promise<void> {
+  if (!lastUseIsStale(use.lastUsedAt, use.now)) {
+    return;
+  }
+  try {
+    await use.write((status) => {
+      stampLastUsed(status, use.now);
+    });
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      return;
+    }
+    use.logger.warn(
+      "Credential last_used_at not recorded (best-effort — the request is unaffected)",
+      {
+        credential: use.credential,
+        id: use.id,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+  }
+}

package/src/pipeline/steps/defaults.ts

@@ -15,6 +15,12 @@
  * SpecAudit for definition changes (search recency, version "pushed at"),
  * StatusAudit for operational changes (Recents, lifecycle metadata).
  *
+ * A write the PLATFORM makes on its own (a schedule's clock, a credential's
+ * last-use stamp) takes the narrower `bumpStatusAudit` instead: status-audit
+ * updated_at + event only, never an actor, because no caller made it (Go's
+ * clock bump, "the same two leaves every cloud runtime patch bumps"). Two
+ * flavors, two writers, both wire-visible — keep them distinct.
+ *
  * This module is also the one home of how an id is SPELLED. `generateId`
  * mints `{prefix}_{ulid}`; `derivedId` is its sibling for the kinds
  * metadata.proto names as deriving their id from a natural key instead
@@ -175,6 +181,27 @@ export function setAuditFieldsForUpdate(
   );
 }
 
+/**
+ * Stamps the status-audit slot for a write the platform makes on its own —
+ * updated_at + event "updated", nothing else (see the module header for why
+ * this is not setAuditFieldsForUpdate). Like that helper it SETS a newly
+ * allocated slot rather than assigning into the existing one (#540); the
+ * slot's created_by/created_at/updated_by carry over unchanged.
+ */
+export function bumpStatusAudit(status: { audit?: ApiResourceAudit }): void {
+  if (status.audit === undefined) {
+    status.audit = create(ApiResourceAuditSchema);
+  }
+  const prior = status.audit.statusAudit;
+  const next =
+    prior === undefined
+      ? create(ApiResourceAuditInfoSchema)
+      : clone(ApiResourceAuditInfoSchema, prior);
+  next.updatedAt = timestampNow();
+  next.event = "updated";
+  status.audit.statusAudit = next;
+}
+
 // Operator identity (stigmer/stigmer#400): installed once at boot — before
 // any request — and read by the identity chassis when it mints the
 // trusted-local CallerIdentity (O2; audit stamping now derives its actor

package/src/temporal/schedule/activities.ts

@@ -20,6 +20,7 @@ import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/ap
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
 import type { Logger } from "../../boot/logger.js";
+import { bumpStatusAudit } from "../../pipeline/steps/defaults.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type { ScheduleTemporalConfig } from "./config.js";
@@ -64,7 +65,7 @@ import {
 } from "./run-ledger.js";
 import type { RunStarter } from "./run-starter.js";
 import type { ScheduleSyncer } from "./syncer.js";
-import { bumpStatusAudit, ensureStatus } from "./status-writes.js";
+import { ensureStatus } from "./status-writes.js";
 
 export interface ScheduleTickActivityDeps {
   readonly store: Store;

package/src/temporal/schedule/run-starter.ts

@@ -49,12 +49,13 @@ import type { Logger } from "../../boot/logger.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
 import type { ScheduleFireCallerMint } from "../../extensions/schedule-fire-caller.js";
 import { ScheduleFireCallerRefusedError } from "../../extensions/schedule-fire-caller.js";
+import { bumpStatusAudit } from "../../pipeline/steps/defaults.js";
 import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type { ScheduleTemporalConfig } from "./config.js";
 import { scheduleModelPinningRefusal } from "./model-pinning.js";
-import { ensureStatus, bumpStatusAudit } from "./status-writes.js";
+import { ensureStatus } from "./status-writes.js";
 
 /**
  * The scheduled session's pinned subject prefix — cross-edition contract

package/src/temporal/schedule/status-writes.ts

@@ -1,26 +1,19 @@
 /**
- * The clock's status-write helpers — port the ensureStatus/bumpStatusAudit
- * pair of pkg/domain/schedule/temporal/syncer.go.
+ * The clock's status-write helper — ports ensureStatus of
+ * pkg/domain/schedule/temporal/syncer.go.
  *
- * bumpStatusAudit is DELIBERATELY narrower than the shared
- * setAuditFieldsForUpdate: Go's clock stamps only status-audit
- * updated_at + event ("the same two leaves every cloud runtime patch
- * bumps") and never an actor — the clock is the platform, not an operator.
- * Controller-side status writes (trigger's last_fire_at stamp, resume's
- * clear) use the FULL shared helper instead, exactly as Go splits
- * steps.SetAuditFieldsForUpdate from the clock's bump. Two flavors, two
- * writers, both wire-visible — keep them distinct.
+ * The clock's audit stamp is the shared `bumpStatusAudit`
+ * (pipeline/steps/defaults.ts): status-audit updated_at + event only, never
+ * an actor — the clock is the platform, not an operator. Controller-side
+ * status writes (trigger's last_fire_at stamp, resume's clear) use the FULL
+ * setAuditFieldsForUpdate instead, exactly as Go splits
+ * steps.SetAuditFieldsForUpdate from the clock's bump.
  */
 import { create } from "@bufbuild/protobuf";
-import { timestampNow } from "@bufbuild/protobuf/wkt";
 
 import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
 import { ScheduleStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/status_pb";
 import type { ScheduleStatus } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/status_pb";
-import {
-  ApiResourceAuditInfoSchema,
-  ApiResourceAuditSchema,
-} from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
 
 /**
  * Returns the schedule's status, materializing the nested message a fresh
@@ -32,19 +25,3 @@ export function ensureStatus(schedule: Schedule): ScheduleStatus {
   }
   return schedule.status;
 }
-
-/**
- * Stamps the status-audit trail for a runtime write — updated_at + event
- * "updated", nothing else (Go bumpStatusAudit; see the module header for
- * why this is not setAuditFieldsForUpdate).
- */
-export function bumpStatusAudit(status: ScheduleStatus): void {
-  if (status.audit === undefined) {
-    status.audit = create(ApiResourceAuditSchema);
-  }
-  if (status.audit.statusAudit === undefined) {
-    status.audit.statusAudit = create(ApiResourceAuditInfoSchema);
-  }
-  status.audit.statusAudit.updatedAt = timestampNow();
-  status.audit.statusAudit.event = "updated";
-}

package/src/temporal/schedule/syncer.ts

@@ -34,12 +34,13 @@ import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/ap
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
 import type { Logger } from "../../boot/logger.js";
+import { bumpStatusAudit } from "../../pipeline/steps/defaults.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type { ScheduleArtifact } from "./artifact.js";
 import { desiredPaused, note } from "./artifact.js";
 import { artifactId } from "./names.js";
-import { bumpStatusAudit, ensureStatus } from "./status-writes.js";
+import { ensureStatus } from "./status-writes.js";
 
 /**
  * The syncer's answer when no Temporal client exists right now (Go