@stigmer/server 3.22.1-dev.20260922095755 → 3.23.0

package/src/artifactstorage/artifact-storage.ts

@@ -58,17 +58,15 @@ export class ArtifactStorageNotFoundError extends Error {
 }
 
 /**
- * A staged upload minted by presignPut: the URL receives the bytes, the
- * stagingKey reads them back through the same driver. Staged blobs are
- * short-lived by contract — the local lane sweeps them on TTL expiry and
- * boot; R2 deployments configure a bucket lifecycle rule on the staging
- * prefix (the §6b driver-side sweep expectation).
+ * A staged upload minted by presignPut: the URL receives the bytes, which
+ * the caller reads back through download() under the key IT named. Staged
+ * blobs are short-lived by contract — the local lane sweeps them on TTL
+ * expiry and boot; a bucket deployment configures a lifecycle rule on the
+ * domain's staging prefix (the §6b driver-side sweep expectation).
  */
 export interface PresignedUpload {
-  /** Accepts one HTTP PUT of exactly the declared byte count. */
+  /** Accepts an HTTP PUT of exactly the declared byte count. */
   readonly url: string;
-  /** Driver key where the staged bytes land, readable via download(). */
-  readonly stagingKey: string;
   /** The TTL actually granted, after per-driver clamping. */
   readonly ttlMs: number;
 }
@@ -98,18 +96,25 @@ export interface ArtifactStorage {
     downloadFilename: string,
   ): Promise<string>;
   /**
-   * A time-limited upload URL for a staging-prefixed blob of exactly
-   * declaredSizeBytes (§6b). Per-driver semantics differ DELIBERATELY and
-   * are contract, not accident: the local backend rides the skill transfer
-   * lane's URL-as-credential slot mechanism (single-use, exact-size
-   * enforced by the lane, TTL clamped to the lane's slot TTL) and answers
-   * only on instances with a staged-upload lane wired — unwired instances
-   * throw the explicit not-configured error, never a silent no-op. The R2
-   * backend presigns a PUT (repeatable within its TTL, size enforced by
-   * the signed Content-Length header, TTL clamped to the 7-day R2
-   * maximum).
+   * A time-limited upload URL for a blob of exactly declaredSizeBytes at
+   * the key the CALLER names (§6b). The key is the domain's: it chooses
+   * the staging prefix its sweep targets and the mapping from its wire
+   * reference, and reads the bytes back through download(key) — the
+   * driver never invents a key of its own. Per-driver semantics differ
+   * DELIBERATELY and are contract, not accident: the local backend rides
+   * the skill transfer lane's URL-as-credential slot mechanism
+   * (single-use, exact-size enforced by the lane, TTL clamped to the
+   * lane's slot TTL) and answers only on instances with a staged-upload
+   * lane wired — unwired instances throw the explicit not-configured
+   * error, never a silent no-op. The R2 backend presigns a PUT
+   * (repeatable within its TTL, size enforced by the signed
+   * Content-Length header, TTL clamped to the 7-day R2 maximum).
    */
-  presignPut(declaredSizeBytes: number, ttlMs: number): Promise<PresignedUpload>;
+  presignPut(
+    key: string,
+    declaredSizeBytes: number,
+    ttlMs: number,
+  ): Promise<PresignedUpload>;
   /** Removes the artifact; missing is not an error. */
   delete(key: string): Promise<void>;
   /** Whether an artifact with the key exists. */
@@ -136,16 +141,16 @@ export type ArtifactStorageDriverFactory = () => ArtifactStorage;
  * the shape it needs and stays ignorant of who provides it.
  */
 export interface StagedUploadLane {
-  /** Reserves a single-use upload slot; returns its reference + TTL. */
-  mint(declaredSizeBytes: number): { ref: string; ttlMs: number };
-  /** The externally-reachable PUT URL for a minted reference. */
-  uploadUrl(ref: string): string;
   /**
-   * The driver key where the reference's staged bytes land — MUST resolve
-   * inside the driver instance's root, or download(stagingKey) could
-   * never read what the lane received.
+   * Reserves a single-use upload slot whose bytes land at `key` under this
+   * driver instance's root — the lane stages into the driver's own tree,
+   * so download(key) reads exactly what the lane received. Returns the
+   * externally-reachable PUT URL and the TTL the lane grants.
    */
-  stagedKey(ref: string): string;
+  reserve(
+    key: string,
+    declaredSizeBytes: number,
+  ): { url: string; ttlMs: number };
 }
 
 export interface ArtifactStorageConfig {
@@ -259,6 +264,7 @@ export class LocalArtifactStorage implements ArtifactStorage {
   }
 
   async presignPut(
+    key: string,
     declaredSizeBytes: number,
     _ttlMs: number,
   ): Promise<PresignedUpload> {
@@ -267,15 +273,13 @@ export class LocalArtifactStorage implements ArtifactStorage {
         "local presigned uploads not configured - no staged-upload lane is wired to this store instance",
       );
     }
+    // The key must be one this instance can read back, or the lane would
+    // stage bytes download(key) can never reach.
+    this.resolveWithinRoot(key);
     // The lane's slot TTL governs, not the caller's ask — the slot
     // registry sweeps on ITS clock, and a URL outliving its slot would be
     // a credential for nothing.
-    const { ref, ttlMs } = this.stagedUploadLane.mint(declaredSizeBytes);
-    return {
-      url: this.stagedUploadLane.uploadUrl(ref),
-      stagingKey: this.stagedUploadLane.stagedKey(ref),
-      ttlMs,
-    };
+    return this.stagedUploadLane.reserve(key, declaredSizeBytes);
   }
 
   async getSignedUrl(

package/src/artifactstorage/r2-storage.ts

@@ -9,8 +9,6 @@
  * that have logic: config validation copy, the 7-day presign clamp, the
  * signed Content-Disposition, and the not-found mapping.
  */
-import { randomBytes } from "node:crypto";
-
 import {
   DeleteObjectCommand,
   GetObjectCommand,
@@ -30,13 +28,6 @@ import {
 /** Go: "R2 has a maximum expiration of 7 days" — presigns clamp here. */
 export const R2_MAX_EXPIRATION_MS = 7 * 24 * 60 * 60 * 1000;
 
-/**
- * Key prefix for presignPut staging blobs (§6b). Pinned as the surface a
- * deployment's bucket lifecycle rule targets: the driver mints under it,
- * operations sweeps it — changing it orphans staged blobs from the sweep.
- */
-export const R2_STAGING_PREFIX = "staging/";
-
 /**
  * Go get_content/get_download_url wrap their storage calls in a 30s
  * context timeout. The TS ArtifactStorage interface carries no signal, so
@@ -167,17 +158,17 @@ export class R2ArtifactStorage implements ArtifactStorage {
   }
 
   async presignPut(
+    key: string,
     declaredSizeBytes: number,
     ttlMs: number,
   ): Promise<PresignedUpload> {
     const clampedMs = Math.min(ttlMs, R2_MAX_EXPIRATION_MS);
-    // Random staging key: the URL is the credential (unguessable), and the
-    // prefix is the contract surface a bucket lifecycle rule sweeps (§6b —
-    // staged uploads the domain never committed must not accrete forever).
-    const stagingKey = `${R2_STAGING_PREFIX}${randomBytes(16).toString("hex")}`;
+    // The key is the caller's: the domain names its staging prefix (the
+    // surface a bucket lifecycle rule sweeps) and keeps the unguessable
+    // part of the URL-as-credential in the reference it hands the client.
     const command = new PutObjectCommand({
       Bucket: this.bucket,
-      Key: stagingKey,
+      Key: key,
       // Signed into the URL: a PUT whose body disagrees with the declared
       // size fails the signature check — R2's arm of the exact-size
       // contract the local lane enforces by counting bytes.
@@ -187,7 +178,7 @@ export class R2ArtifactStorage implements ArtifactStorage {
       const url = await this.presign(this.client, command, {
         expiresIn: Math.floor(clampedMs / 1000),
       });
-      return { url, stagingKey, ttlMs: clampedMs };
+      return { url, ttlMs: clampedMs };
     } catch (error) {
       throw new Error(`r2 presign failed: ${errorText(error)}`, { cause: error });
     }

package/src/authorization/README.md

@@ -34,9 +34,9 @@ editions; the cloud stores what open source computes.
   `spec.execution_visibility`).
 - `tuples.ts` — the tuple vocabulary (object, relation, subject; the string
   notation), the `Person` type (the caller as the model sees them: account id
-  plus the aliases a creator stamp may carry). The model declares no wildcard
-  subject and no condition, so a check carries no context and the parser refuses
-  the `type:*` notation.
+  plus the aliases a creator stamp may carry), `CheckContext` (the
+  `allow_public` parameter: `allow: true` on a point check, `false` in a listing
+  — the cloud's own posture).
 - `person.ts` — the one construction of a `Person`: `resolvePerson` reads the
   caller's account through the port the way whoAmI does, `personFor` builds the
   aliases (the account id and the issuer subject; an email is nobody's) and
@@ -70,8 +70,8 @@ editions; the cloud stores what open source computes.
 
 - `authorizer.ts` — the `Authorizer` driver, arm for arm the cloud's
   (`stigmer-cloud src/authorizer/fga-authorizer.ts`): the four pre-check denials
-  with the Java copy; a kind this edition does not serve denied (a platform
-  capability no self-host holds); the target loaded once through the source;
+  with the Java copy; a kind this edition does not serve denied (so nobody sets
+  public visibility on a self-host); the target loaded once through the source;
   `not-found` for a missing row except on the kinds the cloud never probes
   (`NOT_FOUND_EXEMPT_KINDS`: `identity_account`, `iam_policy` — account ids
   cannot be enumerated); the model's answer with an empty reason on a denial so
@@ -87,14 +87,15 @@ editions; the cloud stores what open source computes.
   counts against the schedule instead of retrying forever.
 - `list-read-scope.ts` — the `ListReadScope` driver, the cloud's twin
   (`stigmer-cloud src/iam/list-read-scope.ts`): every candidate a list lane
-  offers is answered by `can_view`, the same question a get asks — one evaluator
-  walk per candidate over one source seeded with the candidates' facts, so no
-  candidate row is read twice and a parent hop reads each distinct parent once;
-  the enumeration verb (search, recent activity, the two execution summaries —
-  the console library rides it) scans the kind and evaluates the same way, a row
-  that does not decode skipped; the `internal` class keeps everything (the
-  in-process skip); a fault throws and is never an empty answer; an undeclared
-  kind is a consumer bug, loud.
+  offers is answered by `can_view` under the listing context (`allow: false`,
+  the public wildcard suppressed) — one evaluator walk per candidate over one
+  source seeded with the candidates' facts, so no candidate row is read twice
+  and a parent hop reads each distinct parent once; the enumeration verb
+  (search, recent activity, the two execution summaries — the console library
+  rides it) scans the kind and evaluates the same way, a row that does not
+  decode skipped; the `internal` class keeps everything (the in-process skip); a
+  fault throws and is never an empty answer; an undeclared kind is a consumer
+  bug, loud.
 - `posture.ts` — the three postures, named once for the composition root and the
   boot log.
 
@@ -109,14 +110,15 @@ kind. `model/__tests__/registry.test.ts` pins the declared set to the
 open-source tier and each kind's wire permissions to its file;
 `__tests__/wire-permissions.test.ts` pins that every static `(kind, permission)`
 a served RPC asks about is a declared relation. The rest pin the machinery:
-alias matching, the memo, the bounds, the source and the two derived rules on
-both store drivers. The four drivers are pinned arm by arm on both store drivers
-(`__tests__/authorizer.test.ts`, `organization-directory.test.ts`,
-`schedule-fire-caller.test.ts`, `list-read-scope.test.ts` — the adversarial
-cells first: the outsider, the viewer rung, the admin who does not read members'
-conversations, the orphaned execution, the memory with no subject), the posture
-at the wire over three real boots
-(`extensions/__tests__/built-in-authorization-composed.test.ts`, the list lanes
-included, and the two-boot proof that the sole person's lists are byte-identical
-with and without the scope), and the scope's cost is measured rather than
-assumed (`list-read-scope.measure.test.ts`, gated on `AUTHORIZATION_MEASURE=1`).
+alias matching, the wildcard's condition, the memo, the bounds, the source and
+the two derived rules on both store drivers. The four drivers are pinned arm by
+arm on both store drivers (`__tests__/authorizer.test.ts`,
+`organization-directory.test.ts`, `schedule-fire-caller.test.ts`,
+`list-read-scope.test.ts` — the adversarial cells first: the outsider, the
+viewer rung, the admin who does not read members' conversations, the orphaned
+execution, the memory with no subject), the posture at the wire over three real
+boots (`extensions/__tests__/built-in-authorization-composed.test.ts`, the list
+lanes included, and the two-boot proof that the sole person's lists are
+byte-identical with and without the scope), and the scope's cost is measured
+rather than assumed (`list-read-scope.measure.test.ts`, gated on
+`AUTHORIZATION_MEASURE=1`).

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

@@ -2,7 +2,8 @@
  * Pins the built-in Authorizer arm by arm, on both store drivers, against
  * the cloud's driver it mirrors (stigmer-cloud src/authorizer/
  * fga-authorizer.ts): the four pre-check denials with the Java copy; the
- * unserved-kind denial (a platform capability no self-host holds); not-found for a
+ * unserved-kind denial (the server-side half of "nobody sets public
+visibility on a self-host"); not-found for a
  * missing target and a DENIAL for a missing row of an exempt kind (the
  * cloud's probe scope, so account ids cannot be enumerated); allow and
  * deny from the model over a seeded organization — the owner, an admin, a
@@ -221,11 +222,9 @@ describe.each(driverFixtures(SEEDED_KINDS))(
         await grant(orgRole(FOUNDER.accountId, "owner", "acme"));
         await grant(orgRole(ADMIN.accountId, "admin", "acme"));
         await grant(orgRole(MEMBER.accountId, "member", "acme"));
-        // The founder's blueprints: one private, one org-visible, and one
-        // still carrying the retired public level (a row the store
-        // migration has not met); the org-visible one stamped with the
-        // founder's RAW subject (a row a 3.14.x verifier wrote), the
-        // others with the id.
+        // The founder's blueprints: one private, one org-visible, one
+        // public; the org-visible one stamped with the founder's RAW
+        // subject (a row a 3.14.x verifier wrote), the others with the id.
         await seed("agent", "agt_private", {
           org: "acme",
           visibility: ApiResourceVisibility.visibility_private,
@@ -288,10 +287,10 @@ describe.each(driverFixtures(SEEDED_KINDS))(
             UNKNOWN_KIND_DENY_REASON,
           ],
           [
-            "a kind this edition does not serve (platform — nobody holds an operator capability)",
+            "a kind this edition does not serve (platform — nobody sets public visibility)",
             resolved(FOUNDER),
             check(
-              IamPermission.can_view_provider_standing,
+              IamPermission.can_set_public_visibility,
               ApiResourceKind.platform,
               "stigmer",
             ),
@@ -466,7 +465,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
           });
         });
 
-        it("an unprovisioned subject reads nothing — not a private agent, and not a row still carrying the retired public level, which grants no one anything", async () => {
+        it("an unprovisioned subject reads a PUBLIC agent (the point-check context honours the wildcard) and nothing private", async () => {
           const auth = authorizer();
           expect(
             await auth.authorize(
@@ -477,7 +476,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
                 "agt_public",
               ),
             ),
-          ).toEqual({ kind: "deny", reason: "" });
+          ).toEqual({ kind: "allow" });
           expect(
             await auth.authorize(
               idpShaped(STRANGER),

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

@@ -3,7 +3,8 @@
  * built-in authorizer: which tuples a stored row stands for, in exactly
  * the shapes the cloud's tuple driver writes (stigmer-cloud
  * iam/tuple-lifecycle.ts: `organization:<org>#viewer` for the org level,
- * the owner by the kind's attribution, the parent links by `kind_meta`). Two facts are the
+ * the conditional `identity_account:*` for public, the owner by the
+ * kind's attribution, the parent links by `kind_meta`). Two facts are the
  * OSS edition's own and are pinned here by name: the organization's owner
  * is a ROW (2b's role lifecycle), never derived from its creator stamp,
  * or a revoked founder would stay owner; and a stamp that names no person
@@ -95,7 +96,7 @@ describe("deriveTuples — the cloud driver's shapes, from the row", () => {
     ]);
   });
 
-  it("a row that still carries the retired public level derives no viewer tuple at all — no shape reaches every account, and the level's own org floor left with it", () => {
+  it("a public blueprint adds the conditional wildcard AND keeps the org floor", () => {
     expect(
       derivedFor("skill", {
         visibility: ApiResourceVisibility.visibility_public,
@@ -103,6 +104,8 @@ describe("deriveTuples — the cloud driver's shapes, from the row", () => {
     ).toEqual([
       "skill:skill-1#organization@organization:acme",
       "skill:skill-1#owner@identity_account:ida_carol",
+      "skill:skill-1#viewer@identity_account:* with allow_public",
+      "skill:skill-1#viewer@organization:acme#viewer",
     ]);
   });
 
@@ -163,7 +166,7 @@ describe("deriveTuples — the cloud driver's shapes, from the row", () => {
     ).toEqual(["memory:memory-1#organization@organization:acme"]);
   });
 
-  it("an environment carries its creator tuple and an org-viewer at org level, and nothing beyond its org ceiling", () => {
+  it("an environment carries its creator tuple, an org-viewer at org level, and NO public wildcard (the kind's ceiling)", () => {
     expect(
       derivedFor("environment", {
         visibility: ApiResourceVisibility.visibility_org,
@@ -176,7 +179,7 @@ describe("deriveTuples — the cloud driver's shapes, from the row", () => {
     ]);
     expect(
       derivedFor("environment", {
-        visibility: ApiResourceVisibility.visibility_platform,
+        visibility: ApiResourceVisibility.visibility_public,
       }),
     ).toEqual([
       "environment:environment-1#organization@organization:acme",
@@ -506,6 +509,9 @@ describe.each(driverFixtures(SEEDED_KINDS))(
             object,
             "can_view",
             DAVE,
+            {
+              allow: false,
+            },
           ),
         ).toBe(true);
         expect(rowReads).toBe(1);
@@ -701,6 +707,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
           parseObjectRef(object),
           relation,
           person,
+          { allow: true },
         );
       }
 

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

@@ -1,10 +1,11 @@
 /**
  * Pins the evaluator's semantics the store tests cannot express (the
  * cloud's `.fga.yaml` documents prove the model's answers; this file
- * proves the machinery under them): how a person matches a tuple, that a
- * direct tuple outside the line's type restriction is ignored (model drift
- * fails closed), how far a resolution may walk, and that a declaration
- * cycle or an undeclared target is a thrown fault and never a silent deny.
+ * proves the machinery under them): how a person matches a tuple, what
+ * the `allow_public` context does, that a direct tuple outside the line's
+ * type restriction is ignored (model drift fails closed), how far a
+ * resolution may walk, and that a declaration cycle or an undeclared
+ * target is a thrown fault and never a silent deny.
  *
  * The fixture source is the in-memory one the store-test kit uses, so the
  * two proofs share one tuple vocabulary. Where a case needs a shape the
@@ -29,6 +30,7 @@ import {
   direct,
   from,
   objectOf,
+  publicWith,
   union,
   usersetOf,
 } from "../model/rewrite.js";
@@ -54,17 +56,22 @@ function person(accountId: string, ...aliases: string[]): Person {
   return { accountId, aliases: new Set([accountId, ...aliases]) };
 }
 
+const RESOLVE = { allow: true };
+const LIST = { allow: false };
+
 async function allowed(
   source: TupleSource,
   object: string,
   relation: string,
   who: Person,
+  context = RESOLVE,
 ): Promise<boolean> {
   return checkRelation(
     { model: builtInModel, source },
     parseObjectRef(object),
     relation,
     who,
+    context,
   );
 }
 
@@ -93,17 +100,67 @@ describe("a person against a direct tuple", () => {
   });
 });
 
-describe("a stranger against a row with no grant that names them", () => {
-  it("reads nothing: no subject form reaches every account, so a stranger holds no relation on a row they were not granted", async () => {
-    const source = newInMemoryTupleSource([
-      tuple("agent:open#organization@organization:acme"),
-      tuple("agent:open#owner@identity_account:ida_carol"),
-      tuple("agent:open#viewer@organization:acme#viewer"),
-    ]);
-    const stranger = person("ida_mallory");
+describe("the public wildcard and its condition", () => {
+  const publicViewer = (object: string): Tuple => ({
+    object: parseObjectRef(object),
+    relation: "viewer",
+    subject: {
+      form: "wildcard",
+      type: "identity_account",
+      condition: "allow_public",
+    },
+  });
+  const source = newInMemoryTupleSource([
+    tuple("agent:open#organization@organization:acme"),
+    publicViewer("agent:open"),
+  ]);
+  const stranger = person("ida_mallory");
+
+  it("reads for anyone on a point check (the cloud's `allow: true`) and for nobody in a listing (`allow: false`)", async () => {
     expect(await allowed(source, "agent:open", "can_view", stranger)).toBe(
-      false,
+      true,
     );
+    expect(
+      await allowed(source, "agent:open", "can_view", stranger, LIST),
+    ).toBe(false);
+  });
+
+  it("ignores a wildcard tuple that carries no condition where the line demands one — a tuple the cloud could never have written", async () => {
+    const bare = newInMemoryTupleSource([
+      tuple("agent:open#viewer@identity_account:*"),
+    ]);
+    expect(await allowed(bare, "agent:open", "can_view", stranger)).toBe(false);
+  });
+
+  it("is a thrown fault under a condition the transcript names but the evaluator does not know — a model that grew a condition", async () => {
+    const grown = declareKind({
+      kind: ApiResourceKind.agent,
+      schema: AgentSchema,
+      source: "test/grown.fga",
+      relations: [
+        ["viewer", direct(publicWith("identity_account", "after_hours"))],
+      ],
+    });
+    const afterHours = newInMemoryTupleSource([
+      {
+        object: parseObjectRef("agent:open"),
+        relation: "viewer",
+        subject: {
+          form: "wildcard",
+          type: "identity_account",
+          condition: "after_hours",
+        },
+      },
+    ]);
+    await expect(
+      checkRelation(
+        { model: newModel([grown]), source: afterHours },
+        parseObjectRef("agent:open"),
+        "viewer",
+        stranger,
+        RESOLVE,
+      ),
+    ).rejects.toMatchObject({ reason: "unknown-condition" });
   });
 });
 
@@ -220,6 +277,7 @@ describe("the walk itself", () => {
         parseObjectRef("agent:n0"),
         "next",
         person("ida_nobody"),
+        RESOLVE,
       ),
     ).rejects.toMatchObject({ reason: "resolution-depth-exceeded" });
   });
@@ -240,6 +298,7 @@ describe("the walk itself", () => {
         parseObjectRef("agent:x"),
         "a",
         person("ida_nobody"),
+        RESOLVE,
       ),
     ).rejects.toBeInstanceOf(AuthorizationEvaluationError);
   });
@@ -273,7 +332,7 @@ describe("declareKind validates a transcript at load", () => {
         source: "test/bad.fga",
         relations: [
           ["viewer", direct(objectOf("identity_account"))],
-          ["viewer", direct(usersetOf("organization", "viewer"))],
+          ["viewer", direct(publicWith("identity_account", "allow_public"))],
         ],
       }),
     ).toThrow("declared twice");

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

@@ -50,7 +50,7 @@ describe("rowFactsOf against the tuple lifecycle's own resolution", () => {
     for (const visibility of [
       ApiResourceVisibility.visibility_private,
       ApiResourceVisibility.visibility_org,
-      ApiResourceVisibility.visibility_platform,
+      ApiResourceVisibility.visibility_public,
     ]) {
       it(`${declaration.type} at ${ApiResourceVisibility[visibility]}: the same parent links and visibility shapes`, () => {
         const row = fixtureRow(declaration, {
@@ -133,7 +133,7 @@ describe("a list candidate against the loaded row — the facts' two producers",
     for (const visibility of [
       ApiResourceVisibility.visibility_private,
       ApiResourceVisibility.visibility_org,
-      ApiResourceVisibility.visibility_platform,
+      ApiResourceVisibility.visibility_public,
     ]) {
       it(`${declaration.type} at ${ApiResourceVisibility[visibility]}: the candidate the helper builds carries the facts the driver derives from`, async () => {
         const row = fixtureRow(declaration, {