@stigmer/server 3.22.1-dev.20260922095755 → 3.22.1

package/src/authorization/tuples.ts

@@ -1,11 +1,9 @@
 /**
  * The tuple vocabulary of the built-in authorizer — the OpenFGA notions
  * the cloud's model is written in (object, relation, subject; a subject
- * being an object or a userset `type:id#relation`), typed once so the
- * evaluator, the derivation and the store-test kit speak one language. The
- * model declares no wildcard subject and no condition: every reader of a
- * row is an account or the holder of a relation on an object, which is
- * why a check needs no context parameter. Nothing here is
+ * being an object, a userset `type:id#relation`, or the public wildcard
+ * `type:*` under a condition), typed once so the evaluator, the
+ * derivation and the store-test kit speak one language. Nothing here is
  * stored: open source derives every tuple from a row (derived-tuples.ts)
  * or reads it from an IamPolicy row, and this module only names what a
  * tuple IS.
@@ -20,18 +18,28 @@
  * The type is named here; the construction (`personFor`, `resolvePerson`)
  * is person.ts's, so this module stays vocabulary with no I/O.
  *
- * The string forms (`agent:x`, `organization:acme#viewer`) are the
- * notation the cloud's store tests and the IamPolicy proto both use; parse
- * and format are here so the kit and the tests never spell them a second
- * way. The wildcard notation `type:*` is refused by the parser: the model
- * has no line that admits one, so a fixture or a policy that spells it is
- * a mistake to surface, never a subject to carry.
+ * `CheckContext` is the FGA condition context. The one condition the
+ * model declares is `allow_public(allow: bool)` on the public wildcard,
+ * and the cloud's own posture (stigmer-cloud authorizer/fga-authorizer.ts,
+ * the Java BuildCheckRequest) is `allow: true` on a point check — a public
+ * resource reads for any authenticated caller — and `allow: false` in a
+ * listing, which keeps a public wildcard from flooding an organization's
+ * catalog. The parameter is required so a caller states which posture it
+ * is in; there is no default because either one is wrong for the other.
+ *
+ * The string forms (`agent:x`, `organization:acme#viewer`,
+ * `identity_account:*`) are the notation the cloud's store tests and the
+ * IamPolicy proto both use; parse and format are here so the kit and the
+ * tests never spell them a second way.
  */
 import type { Message } from "@bufbuild/protobuf";
 
 /** The FGA type name of the kind every person is: `identity_account:<id>`. */
 export const ACCOUNT_TYPE = "identity_account";
 
+/** The one condition the model declares; it guards the public wildcard. */
+export const ALLOW_PUBLIC_CONDITION = "allow_public";
+
 /** `type:id` — an object of the model. */
 export interface ObjectRef {
   readonly type: string;
@@ -47,6 +55,12 @@ export type Subject =
       readonly form: "userset";
       readonly object: ObjectRef;
       readonly relation: string;
+    }
+  /** `type:*` — every object of the type, honoured only when its condition holds. */
+  | {
+      readonly form: "wildcard";
+      readonly type: string;
+      readonly condition: string | undefined;
     };
 
 export interface Tuple {
@@ -83,6 +97,11 @@ export interface Person {
   readonly aliases: ReadonlySet<string>;
 }
 
+/** The condition parameters of a check (the module header). */
+export interface CheckContext {
+  readonly allow: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // The string notation.
 // ---------------------------------------------------------------------------
@@ -101,8 +120,10 @@ export function formatObjectRef(object: ObjectRef): string {
 }
 
 /**
- * `type:id` or `type:id#relation` → Subject. `type:*` is refused (the
- * module header): no line of the model admits a wildcard subject.
+ * `type:id`, `type:id#relation` or `type:*` → Subject. A wildcard parsed
+ * from text carries no condition; the caller attaches one when its source
+ * says so (the store tests carry it on the tuple, the derivation attaches
+ * the model's).
  */
 export function parseSubject(text: string): Subject {
   const hash = text.indexOf("#");
@@ -115,9 +136,7 @@ export function parseSubject(text: string): Subject {
   }
   const object = parseObjectRef(text);
   if (object.id === "*") {
-    throw new Error(
-      `wildcard subject '${text}' is not admitted: the model declares no wildcard line`,
-    );
+    return { form: "wildcard", type: object.type, condition: undefined };
   }
   return { form: "object", object };
 }
@@ -128,6 +147,10 @@ export function formatSubject(subject: Subject): string {
       return formatObjectRef(subject.object);
     case "userset":
       return `${formatObjectRef(subject.object)}#${subject.relation}`;
+    case "wildcard":
+      return subject.condition === undefined
+        ? `${subject.type}:*`
+        : `${subject.type}:* with ${subject.condition}`;
     default: {
       const exhaustive: never = subject;
       throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);

package/src/domain/agent/__tests__/agent.test.ts

@@ -131,10 +131,8 @@ function agentInput(overrides?: {
 }
 
 /**
- * Seeds an MCP server straight into the store — the agent pipelines only
- * need the row. Org-visible, the level the mcpserver create chain would
- * have stamped: an org-visible agent may reference it under the reference
- * floor, as it would a server created through the API.
+ * Seeds an MCP server straight into the store — the mcpserver controller
+ * arrives with sub-project #9, and the agent pipelines only need the row.
  */
 async function seedMcpServer(opts: {
   id: string;
@@ -157,7 +155,6 @@ async function seedMcpServer(opts: {
       name: opts.slug,
       slug: opts.slug,
       org: opts.org ?? ORG,
-      visibility: ApiResourceVisibility.visibility_org,
     },
     spec: { env: opts.env ?? {} },
     status: connected
@@ -312,11 +309,11 @@ describe("agent enabled-tools validation (#402)", () => {
 });
 
 describe("agent cascade delete (oss#611)", () => {
-  it("sweeps ALL instances by spec.agent_id (cross-org included), deletes same-org shares, keeps a stored cross-org share", async () => {
+  it("sweeps ALL instances by spec.agent_id (cross-org included), deletes same-org shares, keeps cross-org shares", async () => {
     const agent = await command.create(
       agentInput({
         name: "Cascade Target",
-        visibility: ApiResourceVisibility.visibility_org,
+        visibility: ApiResourceVisibility.visibility_public,
       }),
     );
     const agentId = agent.metadata!.id;
@@ -358,10 +355,6 @@ describe("agent cascade delete (oss#611)", () => {
       AgentShareSchema,
       sameOrgShare,
     );
-    // A share in another organization is a row no create admits any more
-    // (a share's agent lives in the share's organization); one written
-    // before that rule is still another organization's row, and the
-    // cascade leaves it as it always did.
     const crossOrgShare = create(AgentShareSchema, {
       metadata: { id: "ash_cross_org", name: "cross-org-share", org: "globex" },
       spec: {

package/src/domain/agent/controller.ts

@@ -42,6 +42,10 @@ import {
   newAuthorizeResolvedTargetStep,
 } from "../../pipeline/steps/authorize-resolved-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
+import {
+  newAuthorizeVisibilityTransitionStep,
+  newGuardPublicVisibilityStep,
+} from "../../pipeline/steps/visibility-gates.js";
 import {
   newBuildNewStateStep,
   setAuditFieldsForUpdate,
@@ -73,8 +77,6 @@ import {
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
 import {
-  collectSpecReferences,
-  newGuardReferenceFloorOnEscalationStep,
   newNormalizeReferencesStep,
   newValidateReferencesStep,
 } from "../../pipeline/steps/references.js";
@@ -166,6 +168,7 @@ async function createAgent(
     .addStep(newResolveSlugStep())
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
+    .addStep(newGuardPublicVisibilityStep(deps.authorizer))
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
     .addStep(newValidateReferencesStep(deps.store))
@@ -358,13 +361,10 @@ async function updateVisibility(
     )
     .addStep(newRecordVisibilityBeforeUpdateStep(UPDATE_VISIBILITY_AGENT_KEY))
     .addStep(newValidateVisibilityUpdateStep())
-    // The reference floor's second door: an agent may not be raised above
-    // the skills and MCP servers it runs with.
     .addStep(
-      newGuardReferenceFloorOnEscalationStep(
-        deps.store,
+      newAuthorizeVisibilityTransitionStep(
         UPDATE_VISIBILITY_AGENT_KEY,
-        [(row) => collectSpecReferences(AgentSchema, row)],
+        deps.authorizer,
       ),
     )
     .addStep(newSetAgentVisibilityStep())