@stigmer/server 3.23.0 → 3.23.1-dev.20260923075205

package/src/extensions/__tests__/built-in-authorization-composed.test.ts

@@ -16,8 +16,9 @@
  *     outsider on an EXISTING resource hears PERMISSION_DENIED, the
  *     cloud's answer; `findMyOrganizations` lists what a person may view
  *     and `find` refuses enumeration; `checkMyPermission` tells the truth;
- *     nobody sets public visibility; an unprovisioned subject
- *     writes nothing until provisioned. The LIST lanes are a member's
+ *     the retired public level is refused for the founder too, as an
+ *     invalid level and not a permission question; an unprovisioned
+ *     subject writes nothing until provisioned. The LIST lanes are a member's
  *     lists: an outsider lists nothing of an organization they hold no
  *     row in; environments and API keys are their owner's even to the
  *     organization's owner; the library (a search) omits a private agent
@@ -26,8 +27,9 @@
  *     provisioned.
  *   - trusted-local: the permissive default stays (one caller,
  *     nothing to separate; the laptop's rows are stamped `"system"`):
- *     tokenless reads, public visibility and organization enumeration all
- *     keep working.
+ *     tokenless reads and organization enumeration keep working, and
+ *     the retired public level is refused here exactly as it is under
+ *     every other posture (the level is gone, not gated).
  *   - a unit's own Authorizer: nothing built in is installed; the unit's
  *     answer stands even against the founder.
  *
@@ -80,7 +82,6 @@ import { loadConfig } from "../../boot/config.js";
 import { composeServer } from "../../boot/compose.js";
 import type { ComposedServer } from "../../boot/compose.js";
 import { metadataOf } from "../../pipeline/steps/shapes.js";
-import { PUBLIC_VISIBILITY_DENY_MESSAGE } from "../../pipeline/steps/visibility-gates.js";
 import type { Store } from "../../store/interface.js";
 import type { Authorizer } from "../authorizer.js";
 import type { ListReadScope } from "../list-read-scope.js";
@@ -132,6 +133,15 @@ function organizationInput(slug: string) {
   };
 }
 
+/**
+ * The one sentence for a level a kind does not support, as the agent chain
+ * answers it (pipeline/steps/validate-visibility.ts builds it from the
+ * kind's config); pinned as bytes because clients render it.
+ */
+const PUBLIC_LEVEL_REFUSED_FOR_AGENT =
+  "agent resources cannot be set to visibility_public. " +
+  "Supported visibility levels: visibility_private, visibility_org, visibility_platform.";
+
 function agentInput(
   name: string,
   visibility: ApiResourceVisibility,
@@ -377,14 +387,14 @@ describe("built-in authorizer (composed server, OIDC with no unit Authorizer: th
     );
   });
 
-  it("nobody sets PUBLIC visibility on an enforcing self-host — the platform gate denies the founder with the policy copy", async () => {
+  it("the retired public level is refused for the founder as an invalid level, before any permission question", async () => {
     const failure = await failureOf(
       createClient(AgentCommandController, asFounder()).create(
         agentInput("Public Agent", ApiResourceVisibility.visibility_public),
       ),
     );
-    expect(failure.code).toBe(Code.PermissionDenied);
-    expect(failure.rawMessage).toBe(PUBLIC_VISIBILITY_DENY_MESSAGE);
+    expect(failure.code).toBe(Code.InvalidArgument);
+    expect(failure.rawMessage).toBe(PUBLIC_LEVEL_REFUSED_FOR_AGENT);
   });
 
   describe("the list lanes (the built-in ListReadScope)", () => {
@@ -595,20 +605,18 @@ describe("built-in authorizer (composed server, trusted-local: the permissive de
     expect(read.metadata?.id).toBe(created.metadata!.id);
   });
 
-  it("the laptop keeps public visibility and organization enumeration — no directory, no platform gate that bites", async () => {
+  it("the laptop keeps organization enumeration and refuses the retired public level like every posture — the level is gone, not gated", async () => {
     const anonymous = transportFor(port);
-    const publicAgent = await createClient(
-      AgentCommandController,
-      anonymous,
-    ).create(
-      agentInput(
-        "Public Laptop Agent",
-        ApiResourceVisibility.visibility_public,
+    const failure = await failureOf(
+      createClient(AgentCommandController, anonymous).create(
+        agentInput(
+          "Public Laptop Agent",
+          ApiResourceVisibility.visibility_public,
+        ),
       ),
     );
-    expect(publicAgent.metadata?.visibility).toBe(
-      ApiResourceVisibility.visibility_public,
-    );
+    expect(failure.code).toBe(Code.InvalidArgument);
+    expect(failure.rawMessage).toBe(PUBLIC_LEVEL_REFUSED_FOR_AGENT);
     const all = await createClient(OrganizationQueryController, anonymous).find(
       { org: ORG },
     );
@@ -617,6 +625,11 @@ describe("built-in authorizer (composed server, trusted-local: the permissive de
 
   it("the laptop's lists are the full scan — no scope composed, the rows stamped `system` included", async () => {
     const anonymous = transportFor(port);
+    // A second agent beside the private one the earlier test created, so
+    // the search below proves a scan and not a single-row coincidence.
+    await createClient(AgentCommandController, anonymous).create(
+      agentInput("Second Laptop Agent", ApiResourceVisibility.visibility_org),
+    );
     const environments = createClient(EnvironmentCommandController, anonymous);
     await environments.create(environmentInput("laptop env one"));
     await environments.create(environmentInput("laptop env two"));

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

@@ -1074,7 +1074,7 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
     });
   });
 
-  it("updateVisibility fires the set-diff transition (org→public keeps the floor)", async () => {
+  it("updateVisibility fires the set-diff transition (org→private deletes the org shape)", async () => {
     const command = createClient(AgentCommandController, portTransport);
     const agent = await command.create(
       create(AgentSchema, {
@@ -1091,12 +1091,12 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
     visibilityEvents.length = 0;
     await command.updateVisibility({
       resourceId: agent.metadata?.id ?? "",
-      visibility: ApiResourceVisibility.visibility_public,
+      visibility: ApiResourceVisibility.visibility_private,
     });
     expect(visibilityEvents).toHaveLength(1);
     const event = visibilityEvents[0]!;
-    expect(event.shapesToCreate).toEqual(["public-viewer"]);
-    expect(event.shapesToDelete).toEqual([]);
+    expect(event.shapesToCreate).toEqual([]);
+    expect(event.shapesToDelete).toEqual(["org-viewer"]);
   });
 
   it("delete fires the cleanup event; a cleanup failure never fails the delete", async () => {

package/src/extensions/__tests__/list-read-scope-composed.test.ts

@@ -10,7 +10,7 @@
  *     narrows, blank spans orgs — lane 6),
  *   - activity.listRecentActivity (enumeration verb, two kinds — lane 22),
  *   - search (enumeration verb feeding the engine allowlist, and the
- *     crossOrgPublic bypass where FGA is never consulted — lane 21),
+ *     proof that no request shape bypasses it — lane 21),
  *   - the OUTAGE arm: a throwing scope answers the sanitized INTERNAL,
  *     never an empty (or full!) list;
  *   - the SERVER'S OWN reads over `inProcessTransport` (stigmer#1207):
@@ -277,20 +277,23 @@ describe("list read scope (composed server, fake scope)", () => {
     ]);
   });
 
-  it("search narrows through the engine allowlist; crossOrgPublic bypasses the scope (lane 21)", async () => {
+  it("search narrows through the engine allowlist on every request shape — nothing bypasses the scope (lane 21)", async () => {
     allowed = new Set(["agt_mine"]);
     const search = createClient(SearchService, transport);
     const scoped = await search.search({ query: "scopedagent" });
     expect(scoped.entries.map((e) => e.id)).toEqual(["agt_mine"]);
 
-    // The Java bypass: public-widened discovery never consults FGA.
+    // The org-filtered shape asks the scope too: the one request shape
+    // that once skipped it (the retired public level's cross-organization
+    // discovery) no longer exists on the wire.
     seenKinds.length = 0;
-    await search.search({
+    const orgScoped = await search.search({
+      kinds: [ApiResourceKind.agent],
       query: "scopedagent",
       org: "acme",
-      crossOrgPublic: true,
     });
-    expect(seenKinds).toEqual([]);
+    expect(orgScoped.entries.map((e) => e.id)).toEqual(["agt_mine"]);
+    expect(seenKinds).toEqual([ApiResourceKind.agent]);
   });
 
   it("a scope outage answers the sanitized INTERNAL — never an unscoped or empty success", async () => {

package/src/extensions/authorization-queries.ts

@@ -32,9 +32,10 @@
  * Semantics the controller and the conformance suite rely on (the Java
  * check-handler posture the cloud's client already implements):
  *
- *   - `check` answers a public grant (a wildcard principal resolves), so
- *     "may I read this public agent" is true for anyone.
- *   - the two listings never expand wildcards, and `listPrincipalIds`
+ *   - `check` resolves usersets (a grant to `organization:acme#member`
+ *     answers true for a member), so "may I read this" is the model's
+ *     answer and not a lookup of who was named.
+ *   - the two listings never expand usersets, and `listPrincipalIds`
  *     answers DIRECT principals only — a listing is an inventory of who
  *     was named, never a resolution of who could reach.
  *   - contextual policies are evaluated as if held, and nothing is written.
@@ -74,7 +75,7 @@ export interface AuthorizationQueryEngine {
   ): Promise<boolean>;
   /**
    * The ids of `resourceKind` resources on which `principal` holds
-   * `relation` (ListAuthorizedResourceIdsInput's field order). Wildcards
+   * `relation` (ListAuthorizedResourceIdsInput's field order). Usersets
    * are not expanded.
    */
   listResourceIds(
@@ -86,7 +87,7 @@ export interface AuthorizationQueryEngine {
   /**
    * The ids of `principalKind` principals holding `relation` on `resource`
    * (ListAuthorizedPrincipalIdsInput's field order). Direct principals
-   * only; wildcards are not expanded.
+   * only; usersets are not expanded.
    */
   listPrincipalIds(
     resource: ApiResourceRef,

package/src/extensions/list-read-scope.ts

@@ -8,7 +8,7 @@
  * is yours). On a multi-tenant edition the same scans serve OTHER
  * tenants' rows, so the cloud baseline (the Java list handlers) narrows
  * every one of them to the caller's FGA-authorized id set (ListObjects
- * on can_view, public wildcards suppressed), with a second guest
+ * on can_view), with a second guest
  * cookie-label rule on the session and agent-execution lanes.
  *
  * This port is the ONE seam for that fork (DD-007 addendum 3: every

package/src/extensions/resource-authorization.ts

@@ -65,14 +65,12 @@ import type { CallerIdentity } from "./identity.js";
  * The visibility tuple shapes of the shared FGA model, named
  * edition-neutrally. The driver maps each to its tuple:
  *   - org-viewer:      <kind>:<id>#viewer@organization:<org>#viewer
- *   - public-viewer:   <kind>:<id>#viewer@identity_account:* (conditional)
  *   - platform-viewer: <kind>:<id>#platform_viewer@identity_provider:<idp>#platform_user
  *     (fans out per IdP the org owns — the driver's lookup, not OSS's)
+ * Every shape names a bounded set of readers; the model has no shape that
+ * reaches every account.
  */
-export type VisibilityTupleShape =
-  | "org-viewer"
-  | "public-viewer"
-  | "platform-viewer";
+export type VisibilityTupleShape = "org-viewer" | "platform-viewer";
 
 /**
  * One resolved structural link from the created resource to a parent

package/src/index.ts

@@ -185,7 +185,6 @@ export {
   newModel,
 } from "./authorization/model/index.js";
 export type {
-  CheckContext,
   ObjectRef,
   Person,
   Subject,

package/src/pipeline/__tests__/supports-visibility.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Pins `supportsVisibility` and `supportedVisibilityLevels`
+ * (pipeline/apiresource-meta.ts), the one predicate behind the
+ * ValidateVisibility doors on every create and updateVisibility chain.
+ *
+ * The retired public level is the reason this file exists: no kind config
+ * declares it any more, so the predicate cannot read a flag for it and must
+ * answer from its own text. The first test walks EVERY kind that has
+ * `kind_meta` and asserts the level is refused; the door is one function,
+ * and this is the pin that it holds for kinds nobody thought to try. The
+ * rest of the file pins the levels that remain against the proto's
+ * declarations for the kinds whose configs differ (a blueprint, an
+ * instance, an org-only kind, a kind with no config), and the copy fragment
+ * both editions build the INVALID_ARGUMENT sentence from.
+ */
+import { describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import {
+  getKindMeta,
+  supportedVisibilityLevels,
+  supportsVisibility,
+} from "../apiresource-meta.js";
+
+const V = ApiResourceVisibility;
+
+/** Every enum member that carries kind_meta (the unknown kind does not). */
+const KINDS_WITH_META: ApiResourceKind[] = Object.values(ApiResourceKind)
+  .filter((value): value is ApiResourceKind => typeof value === "number")
+  .filter((kind) => {
+    try {
+      getKindMeta(kind);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+describe("supportsVisibility", () => {
+  it("refuses the retired public level for every kind", () => {
+    expect(KINDS_WITH_META.length).toBeGreaterThan(20);
+    for (const kind of KINDS_WITH_META) {
+      expect(supportsVisibility(kind, V.visibility_public)).toBe(false);
+    }
+  });
+
+  it("private and unspecified are supported by every kind", () => {
+    for (const kind of KINDS_WITH_META) {
+      expect(supportsVisibility(kind, V.visibility_private)).toBe(true);
+      expect(
+        supportsVisibility(kind, V.api_resource_visibility_unspecified),
+      ).toBe(true);
+    }
+  });
+
+  it("a blueprint kind holds org and platform", () => {
+    expect(supportsVisibility(ApiResourceKind.agent, V.visibility_org)).toBe(
+      true,
+    );
+    expect(
+      supportsVisibility(ApiResourceKind.agent, V.visibility_platform),
+    ).toBe(true);
+  });
+
+  it("an instance kind holds org but never platform (tenant isolation)", () => {
+    expect(
+      supportsVisibility(ApiResourceKind.agent_instance, V.visibility_org),
+    ).toBe(true);
+    expect(
+      supportsVisibility(ApiResourceKind.agent_instance, V.visibility_platform),
+    ).toBe(false);
+  });
+
+  it("an org-only kind holds org alone (environment: secrets never cross the org)", () => {
+    expect(
+      supportsVisibility(ApiResourceKind.environment, V.visibility_org),
+    ).toBe(true);
+    expect(
+      supportsVisibility(ApiResourceKind.environment, V.visibility_platform),
+    ).toBe(false);
+  });
+
+  it("a kind with no visibility config is private-only", () => {
+    expect(supportsVisibility(ApiResourceKind.session, V.visibility_org)).toBe(
+      false,
+    );
+    expect(
+      supportsVisibility(ApiResourceKind.session, V.visibility_platform),
+    ).toBe(false);
+  });
+});
+
+describe("supportedVisibilityLevels (the copy fragment)", () => {
+  it("names the levels that remain, private first, never the retired one", () => {
+    expect(supportedVisibilityLevels(ApiResourceKind.agent)).toBe(
+      "visibility_private, visibility_org, visibility_platform",
+    );
+    expect(supportedVisibilityLevels(ApiResourceKind.agent_instance)).toBe(
+      "visibility_private, visibility_org",
+    );
+    expect(supportedVisibilityLevels(ApiResourceKind.session)).toBe(
+      "visibility_private",
+    );
+    for (const kind of KINDS_WITH_META) {
+      expect(supportedVisibilityLevels(kind)).not.toContain(
+        "visibility_public",
+      );
+    }
+  });
+});

package/src/pipeline/apiresource-meta.ts

@@ -266,9 +266,18 @@ function tierRank(tier: ResourceTier): number {
 }
 
 /**
- * Go SupportsVisibility: PRIVATE and UNSPECIFIED are always supported (no
- * visibility grant); every other level requires the matching supports_*
- * flag. Kinds with no VisibilityConfig are private-only.
+ * Whether a kind may hold a visibility level — the one predicate behind the
+ * ValidateVisibility doors on every create and updateVisibility chain.
+ *
+ * PRIVATE and UNSPECIFIED are always supported (no visibility grant is
+ * written for them); ORG and PLATFORM require the matching supports_* flag
+ * on the kind's VisibilityConfig, so kinds with no config are private-only.
+ * PUBLIC is refused for every kind: the level is retired (it made a row
+ * readable to every account on the server), no config may declare it, and
+ * the answer is fixed here rather than read from a flag that no longer
+ * exists. Every level is named so a level added to the enum must be taught
+ * here before any row can hold it; the closing arm is unreachable by wire
+ * input, because both doors validate the field `defined_only` first.
  */
 export function supportsVisibility(
   kind: ApiResourceKind,
@@ -276,14 +285,19 @@ export function supportsVisibility(
 ): boolean {
   const config = getKindMeta(kind).authorization?.visibility;
   switch (visibility) {
-    case ApiResourceVisibility.visibility_public:
-      return config?.supportsPublic === true;
+    case ApiResourceVisibility.api_resource_visibility_unspecified:
+    case ApiResourceVisibility.visibility_private:
+      return true;
     case ApiResourceVisibility.visibility_org:
       return config?.supportsOrg === true;
     case ApiResourceVisibility.visibility_platform:
       return config?.supportsPlatform === true;
-    default:
-      return true;
+    case ApiResourceVisibility.visibility_public:
+      return false;
+    default: {
+      const exhaustive: never = visibility;
+      throw new Error(`unknown visibility level: ${String(exhaustive)}`);
+    }
   }
 }
 
@@ -298,9 +312,6 @@ export function supportedVisibilityLevels(kind: ApiResourceKind): string {
   if (config?.supportsOrg === true) {
     levels += ", visibility_org";
   }
-  if (config?.supportsPublic === true) {
-    levels += ", visibility_public";
-  }
   if (config?.supportsPlatform === true) {
     levels += ", visibility_platform";
   }

package/src/pipeline/steps/__tests__/authorization-tuples.test.ts

@@ -41,15 +41,10 @@ const caller: CallerIdentity = {
 const V = ApiResourceVisibility;
 
 describe("visibilityShapesFor (the reconciler's level→shape policy)", () => {
-  it("agent (blueprint with org floor): org / public / platform expansions", () => {
+  it("agent (blueprint with org floor): org / platform expansions", () => {
     expect([
       ...visibilityShapesFor(ApiResourceKind.agent, V.visibility_org),
     ]).toEqual(["org-viewer"]);
-    expect(
-      [
-        ...visibilityShapesFor(ApiResourceKind.agent, V.visibility_public),
-      ].sort(),
-    ).toEqual(["org-viewer", "public-viewer"]);
     expect(
       [
         ...visibilityShapesFor(ApiResourceKind.agent, V.visibility_platform),
@@ -60,25 +55,27 @@ describe("visibilityShapesFor (the reconciler's level→shape policy)", () => {
     ]).toEqual([]);
   });
 
-  it("workflow_instance (no org floor): public expands to the wildcard shape alone", () => {
-    expect([
-      ...visibilityShapesFor(
-        ApiResourceKind.workflow_instance,
-        V.visibility_public,
-      ),
-    ]).toEqual(["public-viewer"]);
+  it("the retired public level expands to nothing for every kind — no wildcard shape exists", () => {
+    for (const kind of [
+      ApiResourceKind.agent,
+      ApiResourceKind.workflow_instance,
+      ApiResourceKind.plugin,
+      ApiResourceKind.session,
+    ]) {
+      expect([...visibilityShapesFor(kind, V.visibility_public)]).toEqual([]);
+    }
   });
 
   it("session (no visibility config): every level yields nothing, silently", () => {
     expect([
-      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_public),
+      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_org),
     ]).toEqual([]);
     expect([
-      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_org),
+      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_platform),
     ]).toEqual([]);
   });
 
-  it("agent_instance supports org+public but never platform (tenant isolation)", () => {
+  it("agent_instance supports org but never platform (tenant isolation)", () => {
     expect([
       ...visibilityShapesFor(
         ApiResourceKind.agent_instance,
@@ -101,15 +98,15 @@ describe("diffVisibilityShapes (the reconciler's transition matrix, re-pinned)",
     expect(diff.shapesToDelete).toEqual([]);
   });
 
-  it("unspecified→public creates public + the org floor", () => {
+  it("unspecified→platform creates the platform shape + the org floor", () => {
     const diff = diffVisibilityShapes(
       agent,
       V.api_resource_visibility_unspecified,
-      V.visibility_public,
+      V.visibility_platform,
     );
     expect([...diff.shapesToCreate].sort()).toEqual([
       "org-viewer",
-      "public-viewer",
+      "platform-viewer",
     ]);
     expect(diff.shapesToDelete).toEqual([]);
   });
@@ -124,23 +121,13 @@ describe("diffVisibilityShapes (the reconciler's transition matrix, re-pinned)",
     expect(diff.shapesToDelete).toEqual(["org-viewer"]);
   });
 
-  it("public→org deletes ONLY the wildcard — the shared org shape stays untouched", () => {
+  it("platform→org deletes ONLY the platform shape — the shared org floor stays untouched", () => {
     const diff = diffVisibilityShapes(
       agent,
-      V.visibility_public,
+      V.visibility_platform,
       V.visibility_org,
     );
     expect(diff.shapesToCreate).toEqual([]);
-    expect(diff.shapesToDelete).toEqual(["public-viewer"]);
-  });
-
-  it("platform→public swaps the family shape and never touches the org floor", () => {
-    const diff = diffVisibilityShapes(
-      agent,
-      V.visibility_platform,
-      V.visibility_public,
-    );
-    expect(diff.shapesToCreate).toEqual(["public-viewer"]);
     expect(diff.shapesToDelete).toEqual(["platform-viewer"]);
   });