@stigmer/server 3.21.0 → 3.22.1-dev.20260922095755

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/identity.ts

@@ -112,9 +112,27 @@ export interface IdentityVerifier {
  * rule is load-bearing in open source.
  */
 export function isPlatformPipelineCaller(caller: CallerIdentity): boolean {
-  return (
-    caller.callerClass === "machine" ||
-    caller.callerClass === "internal" ||
-    caller.origin === "in-process"
-  );
+  return caller.callerClass === "machine" || isServerComposedRequest(caller);
+}
+
+/**
+ * Whether the request `caller` arrived on was composed by the server's own
+ * code rather than presented on the wire: the `internal` class (the server
+ * acting as itself) or ANY identity that entered through the in-process
+ * transport (a propagated person the server is building a request for,
+ * such as the default-instance self-heal that creates as the run's human
+ * for attribution). The serving chassis strips the propagation header, so
+ * the wire cannot claim this.
+ *
+ * This is the trust arm the label guard, the memory-capture gate and the
+ * execution-context create check share: what a server-composed request
+ * carries was decided by the service code that built it, and the
+ * entry-point request already passed its own gate. It is NARROWER than
+ * `isPlatformPipelineCaller`: a wire `machine` account is one of the
+ * platform's pipelines but its request is still the wire's, so a step
+ * that trusts server-composed state (a reserved label, a default
+ * instance's provenance) must key on this predicate and never on that one.
+ */
+export function isServerComposedRequest(caller: CallerIdentity): boolean {
+  return caller.callerClass === "internal" || caller.origin === "in-process";
 }

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
@@ -48,11 +48,27 @@
  *     authorization-backend outage surfaces as the pipeline's sanitized
  *     INTERNAL, exactly the Java baseline (DD-007: unavailable is never
  *     softened).
- *   - The scope receives whatever identity the call carries, including
- *     the in-process `internal` class — the driver owns that arm's
- *     semantics (the Java baseline propagates the original caller
- *     through in-process calls, so a composed driver normally never
- *     sees `internal` on these lanes).
+ *   - THE `internal` CLASS IS ANSWERED HERE, NEVER OFFERED TO
+ *     `restrictListEntries`. The server acting as itself over the
+ *     in-process transport (boot/inprocess.ts mints the class; nothing
+ *     else can) is the server's own trust domain, on list lanes exactly
+ *     as on the Authorize step, which returns for the class before any
+ *     Authorizer is asked (pipeline/steps/authorize.ts). The helper
+ *     below returns the org-narrowed rows for that class before the
+ *     scope is consulted. The rule is class-only, like the step's: a
+ *     caller PROPAGATED through the in-process header keeps its own
+ *     class and stays scoped. Why here and not in a driver: a driver
+ *     answering "every offered id" for the class must be written once
+ *     per edition and is a silent short list the day one edition
+ *     forgets (stigmer#1207: a composed driver scoped the class and
+ *     every server-internal list read came back empty — the
+ *     personal-environment reads at execution-context creation and MCP
+ *     connect in this repository, and a composition's own in-process
+ *     readers of a session's executions).
+ *     The enumeration verb is a wire caller's verb: no in-process edge
+ *     reaches `authorizedResourceIds`, and only a scanning driver can
+ *     say "all", so that verb's internal arm stays the driver's and is
+ *     stated in its doc below.
  *   - THE SCOPE IS THE LAST PER-ROW PREDICATE IN A LANE (stigmer-cloud
  *     20260913.04 T02, Q-LB-11). Every request predicate a lane applies
  *     — the request's org, a phase, labels, a parent id, filter criteria
@@ -157,6 +173,13 @@ export interface ListReadScope {
    * answer — consumers map it to their lane's empty shape without
    * touching the store. A scope may throw on a kind it was never ruled
    * to serve (a consumer bug by contract).
+   *
+   * The `internal` class CAN reach this verb (no helper stands between a
+   * consumer and it), and the driver owns that arm: a scanning driver
+   * answers every id of the kind, an engine-backed one answers what its
+   * engine holds for the class. No in-process edge reaches an
+   * enumeration lane today, so the two answers have never met a caller;
+   * a consumer that adds one reads this line first.
    */
   authorizedResourceIds(
     caller: CallerIdentity,
@@ -168,6 +191,12 @@ export interface ListReadScope {
    * baseline: the authorized-ids intersection plus the guest
    * cookie-label rule where the lane carries it). The result must be a
    * subset of the offered ids — a scope only narrows.
+   *
+   * `caller` is never the `internal` class: `restrictListByReadScope`,
+   * the one consumption idiom, answers that class before any driver is
+   * asked (the header's contract line). A driver that is offered it has
+   * been reached around the idiom and should refuse loudly rather than
+   * evaluate the server as a person (the built-in driver does).
    */
   restrictListEntries(
     caller: CallerIdentity,
@@ -209,8 +238,13 @@ export interface ScopedListResource {
  *     permission-bounded across orgs, verified per lane in the entry's
  *     census — lanes Java does not org-narrow pass ""), then to the kept
  *     ids. The same set either way (both are per-row predicates); the
- *     order is the header's second-to-last contract line: the scope sees
- *     the org's rows, not the kind's;
+ *     order is the header's contract line: the scope sees the org's
+ *     rows, not the kind's;
+ *   - scope composed, caller `internal` → the org-narrowed rows, the
+ *     scope never asked and no candidate built (the header's contract
+ *     line). The org predicate is the REQUEST's, not the caller's, so
+ *     the server's own read of a cross-org lane still honours the org
+ *     it asked for; only the caller predicate is skipped;
  *   - every candidate carries the row's authorization facts, and the
  *     candidates of a kind whose authorization is its parent's name that
  *     parent again as `authorizationParent` — one of the facts' parent
@@ -231,6 +265,12 @@ export async function restrictListByReadScope<T extends ScopedListResource>(
     requestOrg === ""
       ? resources
       : resources.filter((resource) => resource.metadata?.org === requestOrg);
+  // The server acting as itself: the trust-domain rule of the Authorize
+  // step, applied to a list answer — the caller predicate is skipped, the
+  // request's org predicate above is not (the header's contract line).
+  if (caller.callerClass === "internal") {
+    return [...offered];
+  }
   const parentOf = authorizationParentReader(kind);
   const entries: ListEntryMeta[] = offered.map((resource) => {
     const entry: ListEntryMeta = {

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"]);
   });