@stigmer/server 3.22.1-dev.20260922095755 → 3.23.0

package/src/authorization/__tests__/store-tests.test.ts

@@ -50,18 +50,22 @@ const FIXTURES = new URL("./fixtures/fga/", import.meta.url);
  */
 const DOCUMENTS = [
   "agent-channel-owner.fga.yaml",
+  "agent-instance-creation.fga.yaml",
   "agent-share-owner.fga.yaml",
   "artifact-org-and-owner.fga.yaml",
   "blueprint-private-visibility.fga.yaml",
   "channel-app-owner.fga.yaml",
   "channel-participation.fga.yaml",
   "channel-session-visibility.fga.yaml",
+  "cross-org-share-creation.fga.yaml",
   "default-instance-inheritance.fga.yaml",
+  "mcp-server-authoring.fga.yaml",
   "memory-subject-only.fga.yaml",
   "org-admin-owner-inheritance.fga.yaml",
   "org-shared-environment.fga.yaml",
   "platform-visibility.fga.yaml",
   "provider-standing-viewer.fga.yaml",
+  "public-visibility-setter.fga.yaml",
   "reserved-label-writer.fga.yaml",
   "schedule-owner.fga.yaml",
   "schedule-session-visibility.fga.yaml",
@@ -98,7 +102,7 @@ const SKIPPED_PINNED: ReadonlyArray<string> = [
   "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:eve <artifact> :: list-objects",
   "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:victor <artifact> :: list-objects",
   "blueprint-private-visibility :: org admin's listable agents include private ones (T08) :: identity_account:oscar <agent> :: list-objects",
-  "blueprint-private-visibility :: org member's listable agents exclude private ones :: identity_account:dave <agent> :: list-objects",
+  "blueprint-private-visibility :: org member's listable agents exclude private ones (wildcard suppressed) :: identity_account:dave <agent> :: list-objects",
   "blueprint-private-visibility :: org viewer's listable agents are exactly the viewer-shaped org-visible ones :: identity_account:vera <agent> :: list-objects",
   "blueprint-private-visibility :: owner's listable agents include everything they authored :: identity_account:carol <agent> :: list-objects",
   "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:alice <channel_app> :: list-objects",
@@ -128,6 +132,9 @@ const SKIPPED_PINNED: ReadonlyArray<string> = [
   // undeclared-kind: platform
   "provider-standing-viewer :: operator may view provider standing, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
   "provider-standing-viewer :: operator may view provider standing, tenants may not :: identity_account:opal platform:stigmer :: undeclared-kind",
+  "public-visibility-setter :: operators may set public visibility, tenants may not :: identity_account:machine platform:stigmer :: undeclared-kind",
+  "public-visibility-setter :: operators may set public visibility, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
+  "public-visibility-setter :: operators may set public visibility, tenants may not :: identity_account:opal platform:stigmer :: undeclared-kind",
   "reserved-label-writer :: operator may write reserved labels, tenants may not :: identity_account:machine platform:stigmer :: undeclared-kind",
   "reserved-label-writer :: operator may write reserved labels, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
   // undeclared-subject-type: identity_provider#platform_user

package/src/authorization/__tests__/tuples.test.ts

@@ -13,7 +13,7 @@ import {
 } from "../tuples.js";
 
 describe("the string notation", () => {
-  it("parses an object and a userset, and an id may carry a colon (issuer subjects do)", () => {
+  it("parses an object, a userset and the wildcard, and an id may carry a colon (issuer subjects do)", () => {
     expect(parseObjectRef("agent:agt_1")).toEqual({
       type: "agent",
       id: "agt_1",
@@ -27,6 +27,11 @@ describe("the string notation", () => {
       object: { type: "organization", id: "acme" },
       relation: "viewer",
     });
+    expect(parseSubject("identity_account:*")).toEqual({
+      form: "wildcard",
+      type: "identity_account",
+      condition: undefined,
+    });
     expect(parseSubject("identity_account:ida_x")).toEqual({
       form: "object",
       object: { type: "identity_account", id: "ida_x" },
@@ -38,24 +43,18 @@ describe("the string notation", () => {
     expect(() => parseObjectRef(":id")).toThrow("not an object reference");
   });
 
-  it("refuses the wildcard notation — no line of the model admits one", () => {
-    expect(() => parseSubject("identity_account:*")).toThrow(
-      "wildcard subject 'identity_account:*' is not admitted",
-    );
-  });
-
-  it("formats a tuple in the proto's notation", () => {
+  it("formats a tuple in the proto's notation, the condition spelled after `with`", () => {
     expect(
       formatTuple({
         object: parseObjectRef("agent:a"),
         relation: "viewer",
         subject: {
-          form: "userset",
-          object: { type: "organization", id: "acme" },
-          relation: "viewer",
+          form: "wildcard",
+          type: "identity_account",
+          condition: "allow_public",
         },
       }),
-    ).toBe("agent:a#viewer@organization:acme#viewer");
+    ).toBe("agent:a#viewer@identity_account:* with allow_public");
     expect(formatSubject(parseSubject("organization:acme#member"))).toBe(
       "organization:acme#member",
     );

package/src/authorization/authorizer.ts

@@ -17,7 +17,9 @@
  *   2. A kind this edition does not serve is `deny` (`kindServedByEdition`,
  *      the predicate 2b's `checkMyPermission` arm 1 uses, so the console
  *      and the server agree by construction). `platform` is the one that
- *      can arrive, through an operator capability no self-host holds.
+ *      arrives, through `can_set_public_visibility` — under the built-in
+ *      posture nobody sets public visibility, the model's own reason for
+ *      making it a platform operator's act.
  *   3. The caller as a person (person.ts) and one derived tuple source for
  *      them; the target loaded ONCE through the source's memoised loader,
  *      so the read that decides not-found is the read the derivation
@@ -29,9 +31,11 @@
  *      member cannot learn which account ids exist. Present or exempt, the
  *      row is then evaluated: the cloud asks OpenFGA whether or not the row
  *      exists, and so does this driver.
- *   5. `checkRelation`. True is `allow`; false is `deny` with an EMPTY
- *      reason, so the method annotation's byte-pinned `error_msg` wins on
- *      the wire, exactly the cloud's genuine-denial path.
+ *   5. `checkRelation` with the point-check context (`allow: true`: a
+ *      public resource reads for any authenticated caller, the cloud's
+ *      posture). True is `allow`; false is `deny` with an EMPTY reason, so
+ *      the method annotation's byte-pinned `error_msg` wins on the wire,
+ *      exactly the cloud's genuine-denial path.
  *
  * Faults. Everything past the pre-checks runs under one guard: a store
  * fault, a person that names nobody (`personFor`), an evaluation fault
@@ -175,6 +179,7 @@ export function newBuiltInAuthorizer(deps: BuiltInAuthorizerDeps): Authorizer {
           object,
           relation,
           person,
+          { allow: true },
         );
         if (allowed) {
           return { kind: "allow" };

package/src/authorization/derived-tuples.ts

@@ -12,6 +12,7 @@
  *   - owner SELF:     <row>#owner@identity_account:<row id>
  *   - creator:        <row>#creator@identity_account:<creator stamp>   (kinds flagged requires_creator_tuple)
  *   - org-viewer:     <row>#viewer@organization:<org>#viewer          (visibility_org; cloud#257's shape)
+ *   - public-viewer:  <row>#viewer@identity_account:* with allow_public
  *   - platform-viewer: none — it fans out over identity providers, a kind this edition does not serve
  *
  * Two facts are this edition's own and are stated here, nowhere else:
@@ -90,7 +91,11 @@ import type {
   Tuple,
   TupleSource,
 } from "./tuples.js";
-import { ACCOUNT_TYPE, formatObjectRef } from "./tuples.js";
+import {
+  ACCOUNT_TYPE,
+  ALLOW_PUBLIC_CONDITION,
+  formatObjectRef,
+} from "./tuples.js";
 
 /**
  * Kinds whose `[identity_account]` owner is recorded as an IamPolicy row
@@ -179,6 +184,12 @@ function visibilitySubject(
             object: { type: "organization", id: org },
             relation: "viewer",
           };
+    case "public-viewer":
+      return {
+        form: "wildcard",
+        type: ACCOUNT_TYPE,
+        condition: ALLOW_PUBLIC_CONDITION,
+      };
     case "platform-viewer":
       return undefined;
     default: {
@@ -350,18 +361,24 @@ function tupleOfRow(row: IamPolicy): Tuple {
     type: principal?.kind ?? "",
     id: principal?.id ?? "",
   };
-  // A principal id of `*` (a wildcard row a cloud database may still hold
-  // from the retired public level) is read as an ordinary object id here:
-  // no person carries `*` among their aliases, so the row matches nobody
-  // and reads as the inert grant it is, never as a fault that would turn
-  // the resource unreadable.
-  const subject: Subject =
-    principal !== undefined && principal.relation !== ""
-      ? {
-          form: "userset",
-          object: principalObject,
-          relation: principal.relation,
-        }
-      : { form: "object", object: principalObject };
+  let subject: Subject;
+  if (principal !== undefined && principal.relation !== "") {
+    subject = {
+      form: "userset",
+      object: principalObject,
+      relation: principal.relation,
+    };
+  } else if (principalObject.id === "*") {
+    // A wildcard row carries no condition of its own; the evaluator
+    // honours it only where a line admits an unconditioned wildcard,
+    // which no line in the model does.
+    subject = {
+      form: "wildcard",
+      type: principalObject.type,
+      condition: undefined,
+    };
+  } else {
+    subject = { form: "object", object: principalObject };
+  }
   return { object, relation: spec?.relation ?? "", subject };
 }

package/src/authorization/evaluator.ts

@@ -1,11 +1,10 @@
 /**
  * The evaluator — OpenFGA's check, over the built-in model and a tuple
  * source, small because the model uses four rewrite forms and nothing
- * else (model/rewrite.ts). `checkRelation(object, relation, person)`
+ * else (model/rewrite.ts). `checkRelation(object, relation, person, context)`
  * answers "does this person hold this relation on this object" the way
  * the cloud's engine answers it over stored tuples, so the two editions
- * share one meaning of authorization. There is no context parameter: the
- * model declares no condition, so a check has no posture to state.
+ * share one meaning of authorization.
  *
  * The walk, in the order a `.fga` line reads:
  *   - `this`: the tuples on (object, relation). A tuple counts only if
@@ -13,7 +12,9 @@
  *     OpenFGA makes at write time, made here at read time, so a derived
  *     tuple the model no longer admits denies instead of allowing. An
  *     object subject matches when it names one of the person's aliases;
- *     a userset subject is resolved on its own object.
+ *     a userset subject is resolved on its own object; the wildcard is
+ *     honoured only under its condition (`allow_public` reads the
+ *     context's `allow`; an unknown condition is a fault).
  *   - `computed`: the same object, another relation.
  *   - `from`: every object the tupleset relation links to (again within
  *     the tupleset line's type restriction), resolved for the relation.
@@ -43,8 +44,19 @@
  */
 import type { Model } from "./model/index.js";
 import type { Rewrite, SubjectType } from "./model/rewrite.js";
-import type { ObjectRef, Person, Subject, TupleSource } from "./tuples.js";
-import { ACCOUNT_TYPE, formatObjectRef, pairKey } from "./tuples.js";
+import type {
+  CheckContext,
+  ObjectRef,
+  Person,
+  Subject,
+  TupleSource,
+} from "./tuples.js";
+import {
+  ACCOUNT_TYPE,
+  ALLOW_PUBLIC_CONDITION,
+  formatObjectRef,
+  pairKey,
+} from "./tuples.js";
 
 /**
  * OpenFGA's default resolution-depth limit (its `resolveNodeLimit`), so
@@ -65,7 +77,8 @@ export type EvaluationFault =
   | "undeclared-target-kind"
   | "internal-caller-offered"
   | "resolution-depth-exceeded"
-  | "resolution-cycle";
+  | "resolution-cycle"
+  | "unknown-condition";
 
 /** A fault in the model or its evaluation — never a denial; the driver maps it to `unavailable`. */
 export class AuthorizationEvaluationError extends Error {
@@ -88,6 +101,7 @@ export async function checkRelation(
   object: ObjectRef,
   relation: string,
   person: Person,
+  context: CheckContext,
 ): Promise<boolean> {
   if (deps.model.byType(object.type) === undefined) {
     throw new AuthorizationEvaluationError(
@@ -95,7 +109,7 @@ export async function checkRelation(
       `no declaration for kind '${object.type}' (target ${formatObjectRef(object)})`,
     );
   }
-  return new Walk(deps, person).resolve(object, relation, 0);
+  return new Walk(deps, person, context).resolve(object, relation, 0);
 }
 
 /** One check's state: the memo and the in-progress set, over one source. */
@@ -106,6 +120,7 @@ class Walk {
   constructor(
     private readonly deps: EvaluationDeps,
     private readonly person: Person,
+    private readonly context: CheckContext,
   ) {}
 
   resolve(
@@ -219,6 +234,15 @@ class Walk {
               allowed.relation === subject.relation,
           ) && (await this.resolve(subject.object, subject.relation, depth + 1))
         );
+      case "wildcard": {
+        const allowed = restriction.some(
+          (entry) =>
+            entry.form === "wildcard" &&
+            entry.type === subject.type &&
+            entry.condition === subject.condition,
+        );
+        return allowed && this.conditionHolds(subject.condition);
+      }
       default: {
         const exhaustive: never = subject;
         throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);
@@ -226,6 +250,18 @@ class Walk {
     }
   }
 
+  private conditionHolds(condition: string | undefined): boolean {
+    switch (condition) {
+      case ALLOW_PUBLIC_CONDITION:
+        return this.context.allow;
+      default:
+        throw new AuthorizationEvaluationError(
+          "unknown-condition",
+          `the model declares no condition '${String(condition)}'`,
+        );
+    }
+  }
+
   /** The object types the tupleset line admits — `[organization]`, `[session]` — from its `this` nodes. */
   private objectTypesOf(
     object: ObjectRef,

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

@@ -11,10 +11,12 @@
  * row a second time. A self-host's lists show a person exactly what a
  * `get` would let them read.
  *
- * Both verbs ask the same question a point check asks, `can_view` on the
- * candidate: the model has no subject whose answer differs between a
- * listing and a get, so a list is exactly the set of rows a get would
- * read.
+ * Both verbs ask under the LISTING context, `allow: false` — the public
+ * wildcard suppressed, the cloud's own posture (its Java
+ * listAuthorizedResourceIds set it): a legacy PUBLIC row reads for any
+ * signed-in person on a point check and never expands into an outsider's
+ * listing; the organization's own people still reach it through the
+ * org-viewer shape public also emits.
  *
  *   - `restrictListEntries`: one derived source for the caller, seeded
  *     with every candidate's facts; one `checkRelation` per unique id —
@@ -82,11 +84,14 @@ import { builtInModel } from "./model/index.js";
 import type { KindDeclaration } from "./model/rewrite.js";
 import type { AccountsByCaller } from "./person.js";
 import { resolvePerson } from "./person.js";
-import type { ObjectRef, Person } from "./tuples.js";
+import type { CheckContext, ObjectRef, Person } from "./tuples.js";
 
 /** The relation every list lane reads through (the cloud's LIST_RELATION). */
 const LIST_RELATION = "can_view";
 
+/** The listing context: the public wildcard suppressed (the module header). */
+const LISTING: CheckContext = { allow: false };
+
 export interface BuiltInListReadScopeDeps {
   readonly store: Store;
   /** The port the grant path writes through — the person's rows are read from the same instance. */
@@ -133,6 +138,7 @@ export function newBuiltInListReadScope(
           object,
           LIST_RELATION,
           person,
+          LISTING,
         );
         return allowed ? facts.id : undefined;
       }),

package/src/authorization/model/agent.ts

@@ -4,8 +4,9 @@
  * read by whoever the visibility axis lets in. The `organization#member`
  * and `organization#viewer` usersets on `viewer` are the org-visibility
  * tuple's two shapes (the cloud writes `#viewer` since cloud#257; `#member`
- * is the legacy shape it still honours), and `platform_viewer` is an
- * identity-provider userset no open-source tuple ever names.
+ * is the legacy shape it still honours), the conditional wildcard is the
+ * public level, and `platform_viewer` is an identity-provider userset no
+ * open-source tuple ever names.
  */
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -16,6 +17,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -42,6 +44,7 @@ export const agentDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/model/agent_instance.ts

@@ -19,6 +19,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -37,6 +38,7 @@ export const agentInstanceDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/model/mcp_server.ts

@@ -12,6 +12,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -38,6 +39,7 @@ export const mcpServerDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/model/plugin.ts

@@ -2,7 +2,8 @@
  * Transcript of fga/model/agentic/plugin.fga — the unit of install, shaped
  * exactly like a skill: an organization-owned blueprint whose owner is the
  * installer (and, through the organization, its admins), whose viewers are
- * the org's members and viewers and the platform viewer. Its verbs are the blueprint set: `can_view`, `can_edit`
+ * the org's members and viewers, public readers when published, and the
+ * platform viewer. Its verbs are the blueprint set: `can_view`, `can_edit`
  * (visibility), `can_delete` (uninstall), `can_grant_access`,
  * `can_view_access`; `can_use` is carried as the model's word for
  * "install from" though no wire permission names it yet.
@@ -20,6 +21,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -46,6 +48,7 @@ export const pluginDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/model/rewrite.ts

@@ -6,17 +6,12 @@
  *   define organization: [organization]                      → direct(objectOf("organization"))
  *   define owner: [identity_account] or admin from organization
  *                → union(direct(objectOf("identity_account")), from("admin", "organization"))
- *   define viewer: [identity_account, organization#member, organization#viewer]
- *                   or owner or platform_viewer
- *                → union(direct(objectOf(...), usersetOf(...), usersetOf(...)),
+ *   define viewer: [identity_account, identity_account:* with allow_public,
+ *                   organization#member, organization#viewer] or owner or platform_viewer
+ *                → union(direct(objectOf(...), publicWith(...), usersetOf(...), usersetOf(...)),
  *                        computed("owner"), computed("platform_viewer"))
  *   define can_view: viewer                                   → computed("viewer")
  *
- * A subject type is an object type or a userset; the model admits no
- * wildcard (`type:*`) and declares no condition, so neither has a form
- * here. The day a line needs one, the transcript cannot be written and
- * the gap is a design act.
- *
  * A declaration file (model/<kind>.ts) is a TRANSCRIPT of its `.fga`
  * file: the same relations, in the file's order, each line rewritten in
  * these builders so a reader with the model open sees the same text, and
@@ -58,6 +53,12 @@ export type SubjectType =
       readonly form: "userset";
       readonly type: string;
       readonly relation: string;
+    }
+  /** `[identity_account:* with allow_public]` — every object of the type, under the condition. */
+  | {
+      readonly form: "wildcard";
+      readonly type: string;
+      readonly condition: string;
     };
 
 export type Rewrite =
@@ -86,6 +87,10 @@ export function usersetOf(type: string, relation: string): SubjectType {
   return { form: "userset", type, relation };
 }
 
+export function publicWith(type: string, condition: string): SubjectType {
+  return { form: "wildcard", type, condition };
+}
+
 export function direct(...subjects: ReadonlyArray<SubjectType>): Rewrite {
   return { node: "this", subjects };
 }

package/src/authorization/model/skill.ts

@@ -14,6 +14,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -40,6 +41,7 @@ export const skillDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/model/workflow.ts

@@ -14,6 +14,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -40,6 +41,7 @@ export const workflowDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/model/workflow_instance.ts

@@ -30,6 +30,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "./rewrite.js";
@@ -83,6 +84,7 @@ export const workflowInstanceDeclaration = declareKind({
       union(
         direct(
           objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
         ),

package/src/authorization/organization-directory.ts

@@ -32,7 +32,8 @@
  * annotation, which is why this driver meets that caller at all: a
  * skip lane hands the directory the identity the interceptor stamped,
  * and no Authorize arm ran before it. Every other caller gets the
- * evaluated list.
+ * evaluated list. The listing context (`allow: false`) is the cloud's,
+ * though no organization line admits a wildcard.
  * The controller loads each id it is handed and skips the ones whose row
  * is gone (grants can outlive rows); the source has already loaded the
  * row once for the evaluation — two primary-key reads per organization,
@@ -101,6 +102,7 @@ export function newBuiltInOrganizationDirectory(
             { type: ORGANIZATION, id },
             "can_view",
             person,
+            { allow: false },
           )
         ) {
           visible.push(id);