@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/src/domain/iampolicy/__tests__/steps.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Pins steps.ts (20260913.01 slice 5): the IamPolicy chains' domain-local
+ * steps. The one with branching logic is ValidateGrantableRole (Q-OR-3 as
+ * refined; Q-S3-3; Q-S5-1): the wire refusal first (an unknown kind is
+ * `Unknown resource kind`, never a role sentence), then the three arms in
+ * order — the PROTO lists no role for the kind → the cloud's
+ * system-managed copy, byte-identical in every edition; the composed
+ * SCOPE lists none → UNIMPLEMENTED naming the editions that serve
+ * per-resource grants; the role is not in proto ∩ scope → the cloud's
+ * second copy listing the intersection in proto order. The intersection
+ * is what keeps a scope from widening the contract by accident.
+ *
+ * Grant and Revoke are proven for the one thing a step adds over the
+ * grant path: the result they leave under POLICY_RESULT_KEY (the revoke
+ * of an absent triple leaves the default instance, Java's contract).
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { IamPolicySpecSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import type { PolicyGrantScope } from "../../../extensions/policy-grant-scope.js";
+import { trustedLocalIdentityFor } from "../../../pipeline/interceptors/auth.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import {
+  PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE,
+  noGrantableRolesMessage,
+  policyIdFor,
+  principalNotGrantableMessage,
+  roleNotGrantableMessage,
+  unknownResourceKindMessage,
+} from "../constants.js";
+import { newIamPolicyGrantPath } from "../grant-path.js";
+import { newOrganizationOnlyGrantScope } from "../grant-scope.js";
+import {
+  POLICY_RESULT_KEY,
+  newGrantStep,
+  newRevokeStep,
+  newValidateGrantableRoleStep,
+} from "../steps.js";
+import { fakeIamPolicyStore, orgRole, triple } from "./support.js";
+
+const caller = trustedLocalIdentityFor({
+  email: "operator@example.com",
+  displayName: "The Operator",
+});
+const silent = createLogger({ level: "error", pretty: false, write: () => {} });
+
+function contextOf(
+  spec: IamPolicySpec,
+): RequestContext<typeof IamPolicySpecSchema> {
+  return new RequestContext(
+    IamPolicySpecSchema,
+    spec,
+    caller,
+    ApiResourceKind.iam_policy,
+  );
+}
+
+async function refusal(
+  run: () => void | Promise<unknown>,
+): Promise<ConnectError> {
+  try {
+    await run();
+  } catch (error) {
+    if (error instanceof ConnectError) return error;
+    throw error;
+  }
+  throw new Error("expected a refusal");
+}
+
+function scopeOf(
+  table: ReadonlyMap<ApiResourceKind, ReadonlyArray<IamRole>>,
+): PolicyGrantScope {
+  return { grantableRoles: (kind) => table.get(kind) ?? [] };
+}
+
+describe("ValidateGrantableRole", () => {
+  const organizationOnly = newValidateGrantableRoleStep(
+    newOrganizationOnlyGrantScope(),
+  );
+
+  it("admits a role the organization's kind_meta lists under the open-source scope", () => {
+    expect(
+      organizationOnly.execute(contextOf(orgRole("ida_bob", "viewer", "acme"))),
+    ).toBeUndefined();
+  });
+
+  it("refuses an unknown resource kind with the wire copy BEFORE any role arm", async () => {
+    const error = await refusal(() =>
+      organizationOnly.execute(
+        contextOf(
+          triple({ kind: "identity_account", id: "ida_bob" }, "viewer", {
+            kind: "nope",
+            id: "x",
+          }),
+        ),
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(unknownResourceKindMessage("nope"));
+  });
+
+  it("arm 1: a kind whose proto lists no role is system-managed in every edition — even when a scope claims otherwise", async () => {
+    const widening = newValidateGrantableRoleStep(
+      scopeOf(new Map([[ApiResourceKind.identity_account, [IamRole.viewer]]])),
+    );
+    const error = await refusal(() =>
+      widening.execute(
+        contextOf(
+          triple({ kind: "identity_account", id: "ida_bob" }, "viewer", {
+            kind: "identity_account",
+            id: "ida_x",
+          }),
+        ),
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(noGrantableRolesMessage("identity_account"));
+  });
+
+  it("arm 2: a kind the proto grants on but the scope excludes is UNIMPLEMENTED with the edition named", async () => {
+    const error = await refusal(() =>
+      organizationOnly.execute(
+        contextOf(
+          triple({ kind: "identity_account", id: "ida_bob" }, "viewer", {
+            kind: "agent",
+            id: "agt_1",
+          }),
+        ),
+      ),
+    );
+    expect(error.code).toBe(Code.Unimplemented);
+    expect(error.rawMessage).toBe(PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE);
+  });
+
+  it("arm 3: a role outside proto ∩ scope is refused with the cloud's copy, listing the intersection in proto order", async () => {
+    const error = await refusal(() =>
+      organizationOnly.execute(contextOf(orgRole("ida_bob", "editor", "acme"))),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(
+      roleNotGrantableMessage("editor", "organization", [
+        "owner",
+        "admin",
+        "member",
+        "viewer",
+      ]),
+    );
+  });
+
+  it("arm 4: a principal that is not a person is refused — a role names an account; a structural link is bootstrapPolicy's (Q-S9-2)", async () => {
+    const error = await refusal(() =>
+      organizationOnly.execute(
+        contextOf(
+          triple({ kind: "organization", id: "other" }, "member", {
+            kind: "organization",
+            id: "acme",
+          }),
+        ),
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(principalNotGrantableMessage("organization"));
+  });
+
+  it("arm 4 runs LAST: a wrong role on a non-person principal hears the role sentence, so every answer the cloud gives today is unchanged", async () => {
+    const error = await refusal(() =>
+      organizationOnly.execute(
+        contextOf(
+          triple({ kind: "organization", id: "other" }, "editor", {
+            kind: "organization",
+            id: "acme",
+          }),
+        ),
+      ),
+    );
+    expect(error.rawMessage).toBe(
+      roleNotGrantableMessage("editor", "organization", [
+        "owner",
+        "admin",
+        "member",
+        "viewer",
+      ]),
+    );
+  });
+
+  it("a scope can only NARROW the proto: a role it adds is clipped from the list", async () => {
+    const widening = newValidateGrantableRoleStep(
+      scopeOf(
+        new Map([
+          [
+            ApiResourceKind.organization,
+            [IamRole.participant, IamRole.viewer, IamRole.owner],
+          ],
+        ]),
+      ),
+    );
+    const error = await refusal(() =>
+      widening.execute(contextOf(orgRole("ida_bob", "participant", "acme"))),
+    );
+    expect(error.rawMessage).toBe(
+      roleNotGrantableMessage("participant", "organization", [
+        "owner",
+        "viewer",
+      ]),
+    );
+    expect(
+      widening.execute(contextOf(orgRole("ida_bob", "viewer", "acme"))),
+    ).toBeUndefined();
+  });
+
+  it("the unknown kind is total for the scope, never a throw from it (Q-S3-3)", async () => {
+    const throwing: PolicyGrantScope = {
+      grantableRoles: () => {
+        throw new Error("a scope must never be asked about an unknown kind");
+      },
+    };
+    const step = newValidateGrantableRoleStep(throwing);
+    const error = await refusal(() =>
+      step.execute(
+        contextOf(
+          triple({ kind: "identity_account", id: "x" }, "viewer", {
+            kind: "garbage",
+            id: "y",
+          }),
+        ),
+      ),
+    );
+    expect(error.rawMessage).toBe(unknownResourceKindMessage("garbage"));
+  });
+});
+
+describe("Grant and Revoke leave their result under POLICY_RESULT_KEY", () => {
+  function pathOverFreshStore() {
+    return newIamPolicyGrantPath({
+      policies: fakeIamPolicyStore(),
+      lifecycle: undefined,
+      logger: silent,
+    });
+  }
+
+  it("Grant leaves the granted row — the same row on the duplicate arm", async () => {
+    const path = pathOverFreshStore();
+    const spec = orgRole("ida_bob", "member", "acme");
+    const first = contextOf(spec);
+    await newGrantStep(path).execute(first);
+    const second = contextOf(spec);
+    await newGrantStep(path).execute(second);
+    expect((first.get(POLICY_RESULT_KEY) as IamPolicy).metadata?.id).toBe(
+      policyIdFor(spec),
+    );
+    expect((second.get(POLICY_RESULT_KEY) as IamPolicy).metadata?.id).toBe(
+      policyIdFor(spec),
+    );
+  });
+
+  it("Revoke leaves the revoked row, or the default instance when there was none (Java's idempotent delete)", async () => {
+    const path = pathOverFreshStore();
+    const spec = orgRole("ida_bob", "member", "acme");
+    await path.grant(spec, caller);
+    const revoked = contextOf(spec);
+    await newRevokeStep(path).execute(revoked);
+    expect((revoked.get(POLICY_RESULT_KEY) as IamPolicy).metadata?.id).toBe(
+      policyIdFor(spec),
+    );
+    const absent = contextOf(spec);
+    await newRevokeStep(path).execute(absent);
+    expect(
+      (absent.get(POLICY_RESULT_KEY) as IamPolicy).metadata?.id ?? "",
+    ).toBe("");
+  });
+});

package/src/domain/iampolicy/__tests__/support.ts

@@ -0,0 +1,195 @@
+/**
+ * Test fixtures for the IamPolicy domain: an in-memory IamPolicyStore with
+ * the primary-key semantics the OSS adapter has (a second save under a held
+ * id is DuplicatePolicyError), a recording lifecycle that captures the two
+ * policy hooks in the order they fire beside the store's writes (the shape
+ * the cloud's service.test.ts used to pin cloud#425), and spec builders in
+ * the contract's own vocabulary. Driver-backed fixtures live with the
+ * drivers (the sqlite and postgres __tests__/support modules under
+ * src/store).
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { IamPolicySpecSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+import type {
+  PolicyGrantedEvent,
+  PolicyRevokedEvent,
+  ResourceAuthorizationLifecycle,
+} from "../../../extensions/resource-authorization.js";
+import { DuplicatePolicyError } from "../store.js";
+import type { IamPolicyStore } from "../store.js";
+
+/** `identity_account:<id>` holds `<relation>` on `organization:<org>` — the organization role. */
+export function orgRole(
+  accountId: string,
+  relation: string,
+  orgId: string,
+): IamPolicySpec {
+  return create(IamPolicySpecSchema, {
+    principal: { kind: "identity_account", id: accountId },
+    relation,
+    resource: { kind: "organization", id: orgId },
+  });
+}
+
+/** Any triple, spelled out. */
+export function triple(
+  principal: { kind: string; id: string; relation?: string },
+  relation: string,
+  resource: { kind: string; id: string },
+): IamPolicySpec {
+  return create(IamPolicySpecSchema, {
+    principal: {
+      kind: principal.kind,
+      id: principal.id,
+      relation: principal.relation ?? "",
+    },
+    relation,
+    resource: { kind: resource.kind, id: resource.id },
+  });
+}
+
+/** What a recording fixture saw, in order. */
+export type RecordedEvent =
+  | { readonly kind: "row-save"; readonly id: string }
+  | { readonly kind: "row-delete"; readonly id: string }
+  | {
+      readonly kind: "granted";
+      readonly id: string;
+      readonly duplicate: boolean;
+    }
+  | {
+      readonly kind: "revoked";
+      readonly id: string | undefined;
+      readonly relation: string;
+    };
+
+export interface FakeIamPolicyStore extends IamPolicyStore {
+  readonly rows: Map<string, IamPolicy>;
+}
+
+/** An in-memory store with the adapter's primary-key semantics; writes are recorded when a log is given. */
+export function fakeIamPolicyStore(
+  recorded?: RecordedEvent[],
+): FakeIamPolicyStore {
+  const rows = new Map<string, IamPolicy>();
+  const all = (): IamPolicy[] => [...rows.values()];
+  const matches = (
+    policy: IamPolicy,
+    principalKind?: string,
+    principalId?: string,
+    resourceKind?: string,
+    resourceId?: string,
+  ): boolean =>
+    (principalKind === undefined ||
+      policy.spec?.principal?.kind === principalKind) &&
+    (principalId === undefined || policy.spec?.principal?.id === principalId) &&
+    (resourceKind === undefined ||
+      policy.spec?.resource?.kind === resourceKind) &&
+    (resourceId === undefined || policy.spec?.resource?.id === resourceId);
+  return {
+    rows,
+    async save(policy) {
+      const id = policy.metadata?.id ?? "";
+      if (rows.has(id)) {
+        throw new DuplicatePolicyError(`IAM policy '${id}' already exists`);
+      }
+      rows.set(id, policy);
+      recorded?.push({ kind: "row-save", id });
+    },
+    async deleteById(id) {
+      rows.delete(id);
+      recorded?.push({ kind: "row-delete", id });
+    },
+    async findById(id) {
+      return rows.get(id);
+    },
+    async findByPrincipal(principalKind, principalId) {
+      return all().filter((p) => matches(p, principalKind, principalId));
+    },
+    async findByResource(resourceKind, resourceId) {
+      return all().filter((p) =>
+        matches(p, undefined, undefined, resourceKind, resourceId),
+      );
+    },
+    async findByPrincipalAndResource(
+      principalKind,
+      principalId,
+      resourceKind,
+      resourceId,
+    ) {
+      return all().filter((p) =>
+        matches(p, principalKind, principalId, resourceKind, resourceId),
+      );
+    },
+    async findByResourceWithRelations(resourceKind, resourceId, relations) {
+      return all().filter(
+        (p) =>
+          matches(p, undefined, undefined, resourceKind, resourceId) &&
+          relations.includes(p.spec?.relation ?? ""),
+      );
+    },
+    async countDistinctPrincipalsByResource(
+      resourceKind,
+      resourceId,
+      principalKind,
+      relations,
+    ) {
+      const seen = new Set<string>();
+      for (const p of all()) {
+        if (
+          matches(p, principalKind, undefined, resourceKind, resourceId) &&
+          relations.includes(p.spec?.relation ?? "")
+        ) {
+          seen.add(`${p.spec?.principal?.kind}:${p.spec?.principal?.id}`);
+        }
+      }
+      return seen.size;
+    },
+    async findScopeTuple(resourceKind, resourceId) {
+      return all().find(
+        (p) =>
+          matches(p, undefined, undefined, resourceKind, resourceId) &&
+          !["identity_account", "team"].includes(
+            p.spec?.principal?.kind ?? "",
+          ) &&
+          !["owner", "creator"].includes(p.spec?.relation ?? ""),
+      );
+    },
+  };
+}
+
+/** A lifecycle that records the two policy hooks and can be told to fail either. */
+export function recordingLifecycle(
+  recorded: RecordedEvent[],
+  faults: { readonly granted?: Error; readonly revoked?: Error } = {},
+): ResourceAuthorizationLifecycle {
+  return {
+    async onResourceCreated() {},
+    async onResourceDeleted() {},
+    async onVisibilityChanged() {},
+    async onPolicyGranted(event: PolicyGrantedEvent) {
+      if (faults.granted !== undefined) {
+        throw faults.granted;
+      }
+      recorded.push({
+        kind: "granted",
+        id: event.policy.metadata?.id ?? "",
+        duplicate: event.duplicate,
+      });
+    },
+    async onPolicyRevoked(event: PolicyRevokedEvent) {
+      if (faults.revoked !== undefined) {
+        throw faults.revoked;
+      }
+      recorded.push({
+        kind: "revoked",
+        id: event.policy?.metadata?.id,
+        relation: event.spec.relation,
+      });
+    },
+  };
+}

package/src/domain/iampolicy/__tests__/wire-refusals.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Pins wire-refusals.ts (20260913.01 slice 5, Q-S5-2): the one place a
+ * kind string that came off the wire, or a whole triple, is turned into
+ * INVALID_ARGUMENT with the domain's byte-pinned copy. Three callers share
+ * it — the grant path, the ValidateGrantableRole step and the fourteen
+ * RPCs' controller — so the table is proven once here; grant-path.test.ts
+ * keeps its own arms and passes through the moved functions unchanged.
+ *
+ * Exactness is contract (Q-OR-9): the derived policy id hashes the spec's
+ * text, so a lenient match would let two spellings of one kind mint two
+ * rows for one grant.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  malformedTripleMessage,
+  unknownPrincipalKindMessage,
+  unknownResourceKindMessage,
+} from "../constants.js";
+import {
+  requireKnownPrincipalKind,
+  requireKnownResourceKind,
+  requireWellFormedTriple,
+} from "../wire-refusals.js";
+import { orgRole, triple } from "./support.js";
+
+function refusal(run: () => unknown): ConnectError {
+  try {
+    run();
+  } catch (error) {
+    if (error instanceof ConnectError) return error;
+    throw error;
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("requireKnownResourceKind / requireKnownPrincipalKind", () => {
+  it("resolve exact enum member names", () => {
+    expect(requireKnownResourceKind("organization")).toBe(
+      ApiResourceKind.organization,
+    );
+    expect(requireKnownPrincipalKind("identity_account")).toBe(
+      ApiResourceKind.identity_account,
+    );
+  });
+
+  for (const garbage of [
+    "Organization",
+    "ORGANIZATION",
+    "",
+    "api_resource_kind_unknown",
+    "constructor",
+    "15",
+  ]) {
+    it(`refuse ${JSON.stringify(garbage)} as a resource kind with the cloud's copy`, () => {
+      const error = refusal(() => requireKnownResourceKind(garbage));
+      expect(error.code).toBe(Code.InvalidArgument);
+      expect(error.rawMessage).toBe(unknownResourceKindMessage(garbage));
+    });
+  }
+
+  it("refuse an unknown principal kind with the principal sentence", () => {
+    const error = refusal(() => requireKnownPrincipalKind("team-ish"));
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(unknownPrincipalKindMessage("team-ish"));
+  });
+});
+
+describe("requireWellFormedTriple", () => {
+  it("answers both refs and both resolved kinds for a well-formed triple", () => {
+    const admitted = requireWellFormedTriple(orgRole("ida_a", "admin", "acme"));
+    expect(admitted.resourceKind).toBe(ApiResourceKind.organization);
+    expect(admitted.principalKind).toBe(ApiResourceKind.identity_account);
+    expect(admitted.resource.id).toBe("acme");
+    expect(admitted.principal.id).toBe("ida_a");
+  });
+
+  it("refuses a delimiter in any field BEFORE either kind is resolved (Q-S2-1)", () => {
+    const error = refusal(() =>
+      requireWellFormedTriple(
+        triple({ kind: "garbage", id: "a#b" }, "viewer", {
+          kind: "garbage",
+          id: "x",
+        }),
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(malformedTripleMessage("principal.id"));
+  });
+
+  it("refuses the resource kind before the principal kind — the cloud's order", () => {
+    const error = refusal(() =>
+      requireWellFormedTriple(
+        triple({ kind: "nope", id: "a" }, "viewer", {
+          kind: "also-nope",
+          id: "x",
+        }),
+      ),
+    );
+    expect(error.rawMessage).toBe(unknownResourceKindMessage("also-nope"));
+  });
+
+  it("refuses an unknown principal kind once the resource kind is known", () => {
+    const error = refusal(() =>
+      requireWellFormedTriple(
+        triple({ kind: "nope", id: "a" }, "viewer", {
+          kind: "organization",
+          id: "acme",
+        }),
+      ),
+    );
+    expect(error.rawMessage).toBe(unknownPrincipalKindMessage("nope"));
+  });
+});