@stigmer/server 3.22.1-dev.20260922095755 → 3.23.0

package/src/pipeline/apiresource-meta.ts

@@ -266,18 +266,9 @@ function tierRank(tier: ResourceTier): number {
 }
 
 /**
- * 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.
+ * 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.
  */
 export function supportsVisibility(
   kind: ApiResourceKind,
@@ -285,19 +276,14 @@ export function supportsVisibility(
 ): boolean {
   const config = getKindMeta(kind).authorization?.visibility;
   switch (visibility) {
-    case ApiResourceVisibility.api_resource_visibility_unspecified:
-    case ApiResourceVisibility.visibility_private:
-      return true;
+    case ApiResourceVisibility.visibility_public:
+      return config?.supportsPublic === true;
     case ApiResourceVisibility.visibility_org:
       return config?.supportsOrg === true;
     case ApiResourceVisibility.visibility_platform:
       return config?.supportsPlatform === true;
-    case ApiResourceVisibility.visibility_public:
-      return false;
-    default: {
-      const exhaustive: never = visibility;
-      throw new Error(`unknown visibility level: ${String(exhaustive)}`);
-    }
+    default:
+      return true;
   }
 }
 
@@ -312,6 +298,9 @@ 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,10 +41,15 @@ const caller: CallerIdentity = {
 const V = ApiResourceVisibility;
 
 describe("visibilityShapesFor (the reconciler's level→shape policy)", () => {
-  it("agent (blueprint with org floor): org / platform expansions", () => {
+  it("agent (blueprint with org floor): org / public / 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),
@@ -55,27 +60,25 @@ describe("visibilityShapesFor (the reconciler's level→shape policy)", () => {
     ]).toEqual([]);
   });
 
-  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("workflow_instance (no org floor): public expands to the wildcard shape alone", () => {
+    expect([
+      ...visibilityShapesFor(
+        ApiResourceKind.workflow_instance,
+        V.visibility_public,
+      ),
+    ]).toEqual(["public-viewer"]);
   });
 
   it("session (no visibility config): every level yields nothing, silently", () => {
     expect([
-      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_org),
+      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_public),
     ]).toEqual([]);
     expect([
-      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_platform),
+      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_org),
     ]).toEqual([]);
   });
 
-  it("agent_instance supports org but never platform (tenant isolation)", () => {
+  it("agent_instance supports org+public but never platform (tenant isolation)", () => {
     expect([
       ...visibilityShapesFor(
         ApiResourceKind.agent_instance,
@@ -98,15 +101,15 @@ describe("diffVisibilityShapes (the reconciler's transition matrix, re-pinned)",
     expect(diff.shapesToDelete).toEqual([]);
   });
 
-  it("unspecified→platform creates the platform shape + the org floor", () => {
+  it("unspecified→public creates public + the org floor", () => {
     const diff = diffVisibilityShapes(
       agent,
       V.api_resource_visibility_unspecified,
-      V.visibility_platform,
+      V.visibility_public,
     );
     expect([...diff.shapesToCreate].sort()).toEqual([
       "org-viewer",
-      "platform-viewer",
+      "public-viewer",
     ]);
     expect(diff.shapesToDelete).toEqual([]);
   });
@@ -121,13 +124,23 @@ describe("diffVisibilityShapes (the reconciler's transition matrix, re-pinned)",
     expect(diff.shapesToDelete).toEqual(["org-viewer"]);
   });
 
-  it("platform→org deletes ONLY the platform shape — the shared org floor stays untouched", () => {
+  it("public→org deletes ONLY the wildcard — the shared org shape stays untouched", () => {
     const diff = diffVisibilityShapes(
       agent,
-      V.visibility_platform,
+      V.visibility_public,
       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"]);
   });
 

package/src/pipeline/steps/__tests__/visibility-gates.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Pins the PUBLIC-visibility operator gates (C2 Stage 3, the Java
+ * PublicVisibilityEscalationPolicy port): the create door fires only on a
+ * new state declaring PUBLIC, the update door only on an ESCALATION to
+ * public (re-asserting stored public passes), both answer the Java deny
+ * copy on denial and pass under the permissive default (OSS
+ * byte-identity), internal callers skip, and a missing loaded target is
+ * a loud wiring fault.
+ */
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { Authorizer, AuthzCheck } from "../../../extensions/authorizer.js";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { RequestContext } from "../../request-context.js";
+import { newPermissiveSingleTeamAuthorizer } from "../authorize.js";
+import {
+  newAuthorizeVisibilityTransitionStep,
+  newGuardPublicVisibilityStep,
+  PUBLIC_VISIBILITY_DENY_MESSAGE,
+} from "../visibility-gates.js";
+
+const USER: CallerIdentity = {
+  identityId: "ida_alice",
+  callerClass: "user",
+  issuer: "stigmer",
+  rawToken: "tok",
+};
+
+const TARGET_KEY = "updateVisibilityAgent";
+
+function denying(observed?: AuthzCheck[]): Authorizer {
+  return {
+    authorize: (_caller, check) => {
+      observed?.push(check);
+      return Promise.resolve({ kind: "deny", reason: "" });
+    },
+  };
+}
+
+function createCtx(
+  visibility: ApiResourceVisibility,
+): RequestContext<typeof AgentSchema> {
+  return new RequestContext(
+    AgentSchema,
+    create(AgentSchema, { metadata: { name: "a", visibility } }),
+    USER,
+    ApiResourceKind.agent,
+  );
+}
+
+type UvDesc = typeof AgentCommandController.method.updateVisibility.input;
+
+function updateCtx(
+  requested: ApiResourceVisibility,
+  stored: ApiResourceVisibility | undefined,
+): RequestContext<UvDesc> {
+  const ctx = new RequestContext(
+    AgentCommandController.method.updateVisibility.input,
+    create(UpdateVisibilityInputSchema, {
+      resourceId: "agt_1",
+      visibility: requested,
+    }),
+    USER,
+    ApiResourceKind.agent,
+  );
+  if (stored !== undefined) {
+    ctx.set(
+      TARGET_KEY,
+      create(AgentSchema, { metadata: { visibility: stored } }),
+    );
+  }
+  return ctx;
+}
+
+describe("GuardPublicVisibility (the create door)", () => {
+  it("denies a PUBLIC create for non-operators with the Java copy", async () => {
+    const step = newGuardPublicVisibilityStep<typeof AgentSchema>(denying());
+    const error = await step
+      .execute(createCtx(ApiResourceVisibility.visibility_public))
+      ?.catch((e: unknown) => e);
+    expect((error as ConnectError).code).toBe(Code.PermissionDenied);
+    expect((error as ConnectError).rawMessage).toBe(
+      PUBLIC_VISIBILITY_DENY_MESSAGE,
+    );
+  });
+
+  it("non-public creates never reach the Authorizer (the lazy contract)", async () => {
+    const observed: AuthzCheck[] = [];
+    const step = newGuardPublicVisibilityStep<typeof AgentSchema>(
+      denying(observed),
+    );
+    await step.execute(createCtx(ApiResourceVisibility.visibility_org));
+    expect(observed).toEqual([]);
+  });
+
+  it("the permissive default allows public creates (OSS byte-identity)", async () => {
+    const step = newGuardPublicVisibilityStep<typeof AgentSchema>(
+      newPermissiveSingleTeamAuthorizer(),
+    );
+    await expect(
+      Promise.resolve(
+        step.execute(createCtx(ApiResourceVisibility.visibility_public)),
+      ),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("AuthorizeVisibilityTransition (the update door)", () => {
+  it("denies escalation to public with the operator check", async () => {
+    const observed: AuthzCheck[] = [];
+    const step = newAuthorizeVisibilityTransitionStep<UvDesc>(
+      TARGET_KEY,
+      denying(observed),
+    );
+    const error = await step
+      .execute(
+        updateCtx(
+          ApiResourceVisibility.visibility_public,
+          ApiResourceVisibility.visibility_org,
+        ),
+      )
+      ?.catch((e: unknown) => e);
+    expect((error as ConnectError).code).toBe(Code.PermissionDenied);
+    expect((error as ConnectError).rawMessage).toBe(
+      PUBLIC_VISIBILITY_DENY_MESSAGE,
+    );
+    expect(observed).toEqual([
+      {
+        permission: IamPermission.can_set_public_visibility,
+        resourceKind: ApiResourceKind.platform,
+        resourceId: "stigmer",
+      },
+    ]);
+  });
+
+  it("re-asserting a stored PUBLIC is not an escalation", async () => {
+    const step = newAuthorizeVisibilityTransitionStep<UvDesc>(
+      TARGET_KEY,
+      denying(),
+    );
+    await expect(
+      Promise.resolve(
+        step.execute(
+          updateCtx(
+            ApiResourceVisibility.visibility_public,
+            ApiResourceVisibility.visibility_public,
+          ),
+        ),
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  it("non-public targets never reach the Authorizer", async () => {
+    const observed: AuthzCheck[] = [];
+    const step = newAuthorizeVisibilityTransitionStep<UvDesc>(
+      TARGET_KEY,
+      denying(observed),
+    );
+    await step.execute(
+      updateCtx(
+        ApiResourceVisibility.visibility_org,
+        ApiResourceVisibility.visibility_public,
+      ),
+    );
+    expect(observed).toEqual([]);
+  });
+
+  it("a missing loaded target is a loud wiring fault, never a silent pass", async () => {
+    const step = newAuthorizeVisibilityTransitionStep<UvDesc>(
+      TARGET_KEY,
+      denying(),
+    );
+    const error = await step
+      .execute(updateCtx(ApiResourceVisibility.visibility_public, undefined))
+      ?.catch((e: unknown) => e);
+    expect((error as ConnectError).code).toBe(Code.Internal);
+  });
+});

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

@@ -94,15 +94,9 @@ import { metadataOf, parentIdOf } from "./shapes.js";
  * validation).
  *
  * The org floor: kinds flagged defaults_to_org_visibility (blueprints —
- * shared org assets) keep the org-viewer shape at the platform level, so
- * sharing a blueprint beyond the org never hides it from its own org's
- * catalog.
- *
- * The retired public level has no shape here. No stored row holds it once
- * the store migration has run, so no transition FROM it reaches this
- * policy; a deployment that still holds public rows must move them through
- * updateVisibility on the release that knew the level, whose reconciler
- * deletes the wildcard grant, before it runs this one.
+ * shared org assets) keep the org-viewer shape at public and platform
+ * levels, so sharing a blueprint beyond the org never hides it from its
+ * own org's catalog (ListObjects suppresses the public wildcard).
  */
 export function visibilityShapesFor(
   kind: ApiResourceKind,
@@ -118,6 +112,14 @@ export function visibilityShapesFor(
         shapes.add("org-viewer");
       }
       break;
+    case ApiResourceVisibility.visibility_public:
+      if (config?.supportsPublic === true) {
+        shapes.add("public-viewer");
+        if (orgFloor) {
+          shapes.add("org-viewer");
+        }
+      }
+      break;
     case ApiResourceVisibility.visibility_platform:
       if (config?.supportsPlatform === true) {
         shapes.add("platform-viewer");