@stigmer/server 3.15.2-dev.20260913223433 → 3.15.3-dev.20260914100347

package/src/domain/identityaccount/store-contract.ts

@@ -8,23 +8,16 @@
  * `cloud.iam_identity_account` store), so "the port holds" is one
  * statement proven per driver, never restated per repository.
  *
- * Shape. The package's precedent is store/__tests__/store-contract.ts —
- * `describeStoreContract(makeFixture)`: a fresh fixture per test, named
- * escape hatches for the arms the interface cannot express, driver-physical
- * behavior left to each driver's own tests. This kit follows it in
- * everything but the framework: it is consumed by ANOTHER package's tests,
- * so it ships in dist/ and must not import vitest — a devDependency that
- * would enter the root barrel's runtime import graph. It therefore returns
- * cases instead of calling `describe`, asserts through node:assert/strict,
- * and the consumer's framework does `for (const c of cases) it(c.name,
- * c.run)`. Do not "fix" it back to the precedent's vitest shape.
- *
- * Every case makes a FRESH fixture, runs, and cleans up; a failing
- * assertion wins over a failing cleanup. `disconnect` is the one escape
- * hatch: the port has no lifecycle by design (a composition owns its
- * store's), yet "an outage never reads as no account" is the line that
- * matters most, so the fixture cuts the store from its database and the
- * kit asserts that the fault propagates instead of reading as `undefined`.
+ * Shape. The kit is a list of declarations over the port-contract runner
+ * (store/port-contract.ts, lifted from this file in 20260913.01 slice 2
+ * when the IamPolicy kit became the second): the runner owns the fresh
+ * fixture per case, the cleanup, the rule that a failing assertion wins
+ * over a failing cleanup, and the reason the kit returns cases instead of
+ * calling vitest's `describe`. `disconnect` is the one escape hatch: the
+ * port has no lifecycle by design (a composition owns its store's), yet
+ * "an outage never reads as no account" is the line that matters most, so
+ * the fixture cuts the store from its database and the kit asserts that
+ * the fault propagates instead of reading as `undefined`.
  *
  * What the kit deliberately does not carry: open source's primary-key read
  * (the findByField spy) and its derived-id refusal, the cloud's column
@@ -52,32 +45,21 @@ import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityacc
 import { IdentityAccountSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
 import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
 
+import { portContractCases } from "../../store/port-contract.js";
+import type {
+  PortContractCase,
+  PortContractDeclaration,
+  PortContractFixture,
+} from "../../store/port-contract.js";
 import { accountIdFor } from "./constants.js";
 import { DuplicateAccountError } from "./store.js";
 import type { IdentityAccountStore } from "./store.js";
 
-/** One fresh, isolated store per case, plus the one escape hatch the port cannot express. */
-export interface IdentityAccountStoreContractFixture {
-  readonly store: IdentityAccountStore;
-  /**
-   * Cuts the store from its database so every later call is an
-   * infrastructure fault. `cleanup` still runs afterwards and must tolerate
-   * a disconnected store (both OSS drivers' `close` is idempotent; a pool
-   * fixture ends a per-case pool here and skips it in cleanup).
-   */
-  disconnect(): Promise<void>;
-  cleanup(): Promise<void>;
-}
+/** The runner's fixture over this port — the name a driver's test and the barrel know it by. */
+export type IdentityAccountStoreContractFixture =
+  PortContractFixture<IdentityAccountStore>;
 
-export interface IdentityAccountStoreContractCase {
-  /** The contract line, in the port's words; the framework prints it as the test name. */
-  readonly name: string;
-  /** Makes a FRESH fixture, runs the case, cleans up. A failing assertion wins over a failing cleanup. */
-  run(): Promise<void>;
-}
-
-/** A case body over a live fixture; the kit owns the fixture's lifecycle around it. */
-type CaseBody = (fixture: IdentityAccountStoreContractFixture) => Promise<void>;
+export type IdentityAccountStoreContractCase = PortContractCase;
 
 /** A direct account as the domain writes it: id derived from the subject, mode direct. */
 function directAccount(overrides: {
@@ -151,7 +133,7 @@ function subjectsOf(accounts: ReadonlyArray<IdentityAccount>): string[] {
   return accounts.map((account) => account.spec?.idpId ?? "");
 }
 
-const CASES: ReadonlyArray<readonly [string, CaseBody]> = [
+const CASES: ReadonlyArray<PortContractDeclaration<IdentityAccountStore>> = [
   [
     "save then findById round-trips the account",
     async ({ store }) => {
@@ -433,39 +415,9 @@ const CASES: ReadonlyArray<readonly [string, CaseBody]> = [
   ],
 ];
 
-/**
- * Runs `body` over a fresh fixture. The body's failure is the one reported:
- * a cleanup failure after a failed body would otherwise replace the
- * assertion that matters with a teardown detail.
- */
-async function withFixture(
-  makeFixture: () => Promise<IdentityAccountStoreContractFixture>,
-  body: CaseBody,
-): Promise<void> {
-  const fixture = await makeFixture();
-  let failed = false;
-  try {
-    await body(fixture);
-  } catch (error) {
-    failed = true;
-    throw error;
-  } finally {
-    try {
-      await fixture.cleanup();
-    } catch (cleanupError) {
-      if (!failed) {
-        throw cleanupError;
-      }
-    }
-  }
-}
-
 /** The port's cases over `makeFixture`, one fresh fixture per case. */
 export function identityAccountStoreContract(
   makeFixture: () => Promise<IdentityAccountStoreContractFixture>,
 ): ReadonlyArray<IdentityAccountStoreContractCase> {
-  return CASES.map(([name, body]) => ({
-    name,
-    run: () => withFixture(makeFixture, body),
-  }));
+  return portContractCases(CASES, makeFixture);
 }

package/src/extensions/__tests__/composed-support.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared fakes for the composed-server extension proofs (the
+ * `*-composed.test.ts` files): the pieces a test needs to boot
+ * `composeServer` with a fake unit in the cloud's own shape — a declared
+ * require-authentication posture and the unit's OWN verifier — and to talk
+ * to it over the wire as a chosen subject.
+ *
+ * The verifier vouches for an unsigned JWT-shaped token (`header.payload.
+ * unsigned`) and admits its `sub` as a `user` whose identityId is the RAW
+ * subject with an empty issuer: it deliberately does NOT resolve to an
+ * account, exactly like a composition verifier that runs before any row
+ * exists, so a first provisioning runs for real with no network. It passes
+ * on every other token, so the OSS lanes composed ahead of it keep their
+ * claims. Lifted from identity-account-composed.test.ts (20260911.11 slice
+ * 3) when a second composed proof needed the same shape (20260913.01 S1).
+ */
+import path from "node:path";
+
+import type { Interceptor, Transport } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { createLogger } from "../../boot/logger.js";
+import type { CallerIdentity, IdentityVerifier } from "../identity.js";
+
+export const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+/** The smallest config a composed server boots with, everything under `dir`. */
+export function baseConfig(dir: string): Record<string, string> {
+  return {
+    STIGMER_MODEL_REGISTRY_REFRESH: "off",
+    TEMPORAL_HOST_PORT: "127.0.0.1:1",
+    DB_PATH: path.join(dir, "stigmer.db"),
+    STORAGE_PATH: path.join(dir, "storage"),
+    ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+  };
+}
+
+/** An unsigned JWT-shaped token the fake verifier vouches for; idpIdOf reads its `sub` as it reads a real token's. */
+export function fakeJwt(sub: string, email: string): string {
+  const segment = (value: unknown): string =>
+    Buffer.from(JSON.stringify(value)).toString("base64url");
+  return `${segment({ alg: "none" })}.${segment({ sub, email })}.unsigned`;
+}
+
+/** The composition's own verifier (the cloud's shape) — see the module header. */
+export const fakeVerifier: IdentityVerifier = {
+  name: "fake-composition-verifier",
+  verify: (token) => {
+    const segments = token.split(".");
+    if (segments.length !== 3 || segments[2] !== "unsigned") {
+      return Promise.resolve(null);
+    }
+    const claims = JSON.parse(
+      Buffer.from(segments[1] ?? "", "base64url").toString("utf8"),
+    ) as { sub?: unknown; email?: unknown };
+    if (typeof claims.sub !== "string") {
+      return Promise.resolve(null);
+    }
+    const identity: CallerIdentity = {
+      identityId: claims.sub,
+      callerClass: "user",
+      issuer: "",
+      rawToken: token,
+      ...(typeof claims.email === "string" ? { email: claims.email } : {}),
+    };
+    return Promise.resolve(identity);
+  },
+};
+
+export function bearer(token: string): Interceptor {
+  return (next) => (request) => {
+    request.header.set("authorization", `Bearer ${token}`);
+    return next(request);
+  };
+}
+
+/** A gRPC transport to the composed server on `port`, presenting `token` when given. */
+export function transportFor(port: number, token?: string): Transport {
+  return createGrpcTransport({
+    baseUrl: `http://127.0.0.1:${port}`,
+    interceptors: token !== undefined ? [bearer(token)] : [],
+  });
+}

package/src/extensions/__tests__/iam-policy-composed.test.ts

@@ -0,0 +1,373 @@
+/**
+ * Pins the built-in authorization POSTURE end to end (20260913.01,
+ * T01_1_review.md Q-OR-6): `builtInAuthorization = extensions.authorizer
+ * === undefined`, named once in compose.ts. The open-source membership
+ * rules and the built-in role lifecycle exist to feed the built-in
+ * authorizer; a composition that registers its OWN Authorizer has its own
+ * onboarding (the cloud's invitations, its personal-organization step, its
+ * tuple driver) and must get neither of them — otherwise every cloud
+ * organization create would write a second, unasked-for `owner` row and
+ * every first sign-in would hand out roles the cloud never granted.
+ *
+ * The NEGATIVE proof, over a composed server in the cloud's own shape (a
+ * declared require-authentication posture, the unit's verifier, the unit's
+ * Authorizer, no lifecycle driver): an organization created by a signed-in
+ * subject leaves NO policy row; the creator's first provisioning writes
+ * none (no ownership heal); a second subject's first provisioning writes
+ * none (no membership). Green before the domain lands and green after by
+ * design: its value is at the slice that wires compose.ts, where an
+ * unconditional install turns it red. Every negative assertion sits beside
+ * a positive one (the create succeeded, the accounts exist, the unit's
+ * Authorizer WAS consulted) so the file cannot pass vacuously.
+ *
+ * The POSITIVE proof of the WIRING (slice 4), through real boots on both
+ * open-source postures:
+ *   - OIDC with no Authorizer (the unit's verifier alone): the creator
+ *     founds an organization idp-shaped → no row yet; provisions → one
+ *     `owner` row, stamped by the account; founds a SECOND organization
+ *     after provisioning (the verifier still stamps the raw subject) → its
+ *     owner row lands through the subject read of `accountForCaller`
+ *     (Q-S4-1); a newcomer provisions → one `member` row per organization;
+ *     provisions again → nothing new;
+ *   - trusted-local: an organization created over the wire is owned by the
+ *     operator's account; a second boot on the same database writes
+ *     nothing (Q-S4-3); an owner row deleted underneath is written back at
+ *     the next boot (Q-OR-6c).
+ * The positive proof of the RPCs over these rows is
+ * domain/iampolicy/__tests__/iampolicy.test.ts (slice 5).
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { fromBinary } from "@bufbuild/protobuf";
+import { createClient } from "@connectrpc/connect";
+import { afterAll, beforeAll, 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 { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { IdentityAccountCommandController } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/command_pb";
+import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/command_pb";
+import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/query_pb";
+
+import { loadConfig } from "../../boot/config.js";
+import { composeServer } from "../../boot/compose.js";
+import type { ComposedServer } from "../../boot/compose.js";
+import { policyIdFor } from "../../domain/iampolicy/constants.js";
+import { orgRole } from "../../domain/iampolicy/__tests__/support.js";
+import {
+  accountIdFor,
+  localIdpIdFor,
+} from "../../domain/identityaccount/constants.js";
+import {
+  resetOperatorIdentityForTests,
+  setOperatorIdentity,
+} from "../../pipeline/steps/defaults.js";
+import type { Authorizer } from "../authorizer.js";
+import type { ServerExtension } from "../registry.js";
+import {
+  baseConfig,
+  fakeJwt,
+  fakeVerifier,
+  silentLogger,
+  transportFor,
+} from "./composed-support.js";
+
+const CREATOR = "fake|creator";
+const NEWCOMER = "fake|newcomer";
+
+/** The policy rows a composed server's store holds, decoded — the one observation every describe below is about. */
+async function policiesIn(server: ComposedServer): Promise<IamPolicy[]> {
+  const rows = await server.store.listResources(ApiResourceKind.iam_policy);
+  return rows.map((row) => fromBinary(IamPolicySchema, row));
+}
+
+/** `<relation>@<organization>` for every row `accountId` holds, sorted. */
+function rolesHeldBy(
+  policies: ReadonlyArray<IamPolicy>,
+  accountId: string,
+): ReadonlyArray<string> {
+  return policies
+    .filter((p) => p.spec?.principal?.id === accountId)
+    .map((p) => `${p.spec?.relation}@${p.spec?.resource?.id}`)
+    .sort();
+}
+
+function organizationInput(slug: string) {
+  return {
+    apiVersion: "tenancy.stigmer.ai/v1",
+    kind: "Organization",
+    metadata: { name: slug, slug, org: "" },
+    spec: { description: slug },
+  };
+}
+
+describe("iam-policy posture (composed server, a unit's own Authorizer: nothing built in is installed)", () => {
+  let dir: string;
+  let server: ComposedServer;
+  let port: number;
+  let authorizerCalls = 0;
+
+  /** Allows everything and counts — the proof the posture switch saw a registered Authorizer. */
+  const permissiveAuthorizer: Authorizer = {
+    authorize: () => {
+      authorizerCalls += 1;
+      return Promise.resolve({ kind: "allow" });
+    },
+  };
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "iam-policy-composed-"));
+    const unit: ServerExtension = {
+      name: "fake-iam",
+      requireAuthentication: true,
+      identityVerifiers: [fakeVerifier],
+      authorizer: permissiveAuthorizer,
+    };
+    server = await composeServer({
+      config: loadConfig(baseConfig(dir)),
+      logger: silentLogger,
+      extensions: [unit],
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    port = await server.start();
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** The policy rows the composed server's store holds — the one observation the posture is about. */
+  async function policyRows(): Promise<ReadonlyArray<string>> {
+    const rows = await server.store.listResources(ApiResourceKind.iam_policy);
+    return rows.map(
+      (row) => fromBinary(IamPolicySchema, row).metadata?.id ?? "",
+    );
+  }
+
+  it("an organization created by a signed-in subject leaves no policy row — the built-in role lifecycle is not installed", async () => {
+    const asCreator = transportFor(
+      port,
+      fakeJwt(CREATOR, "creator@example.com"),
+    );
+    const created = await createClient(
+      OrganizationCommandController,
+      asCreator,
+    ).create({
+      apiVersion: "tenancy.stigmer.ai/v1",
+      kind: "Organization",
+      metadata: { name: "posture-org", slug: "posture-org", org: "" },
+      spec: { description: "created under a unit's own Authorizer" },
+    });
+    // Organization create is `is_skip_authorization` by annotation (anyone
+    // may found one), so the proof that the posture switch saw a registered
+    // Authorizer is the read that follows: `get` is annotated can_view.
+    await createClient(OrganizationQueryController, asCreator).get({
+      value: "posture-org",
+    });
+
+    expect(created.metadata?.id, "the create itself succeeded").toBe(
+      "posture-org",
+    );
+    expect(
+      authorizerCalls,
+      "the unit's Authorizer was consulted",
+    ).toBeGreaterThan(0);
+    expect(await policyRows()).toEqual([]);
+  });
+
+  it("the creator's first provisioning writes no row — the membership rules' ownership heal is not installed", async () => {
+    const account = await createClient(
+      IdentityAccountCommandController,
+      transportFor(port, fakeJwt(CREATOR, "creator@example.com")),
+    ).provisionMyAccount({});
+
+    expect(account.metadata?.id).toBe(accountIdFor(CREATOR));
+    expect(await policyRows()).toEqual([]);
+  });
+
+  it("a newcomer's first provisioning writes no row — no membership is handed out", async () => {
+    const account = await createClient(
+      IdentityAccountCommandController,
+      transportFor(port, fakeJwt(NEWCOMER, "newcomer@example.com")),
+    ).provisionMyAccount({});
+
+    expect(account.metadata?.id).toBe(accountIdFor(NEWCOMER));
+    expect(await policyRows()).toEqual([]);
+  });
+});
+
+describe("built-in authorization posture (composed server, OIDC with no Authorizer: both rules are installed)", () => {
+  let dir: string;
+  let server: ComposedServer;
+  let port: number;
+  const creatorId = accountIdFor(CREATOR);
+  const newcomerId = accountIdFor(NEWCOMER);
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "iam-policy-built-in-oidc-"));
+    // The unit vouches for tokens and declares the posture, and registers
+    // NO Authorizer — the open-source OIDC self-host's shape.
+    const unit: ServerExtension = {
+      name: "fake-oidc-only",
+      requireAuthentication: true,
+      identityVerifiers: [fakeVerifier],
+    };
+    server = await composeServer({
+      config: loadConfig(baseConfig(dir)),
+      logger: silentLogger,
+      extensions: [unit],
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    port = await server.start();
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("an organization founded idp-shaped, before any account exists, leaves no row yet", async () => {
+    const created = await createClient(
+      OrganizationCommandController,
+      transportFor(port, fakeJwt(CREATOR, "creator@example.com")),
+    ).create(organizationInput("founded-before"));
+
+    expect(created.metadata?.id).toBe("founded-before");
+    expect(await policiesIn(server)).toEqual([]);
+  });
+
+  it("the founder's first provisioning writes exactly one owner row, stamped by the account", async () => {
+    const account = await createClient(
+      IdentityAccountCommandController,
+      transportFor(port, fakeJwt(CREATOR, "creator@example.com")),
+    ).provisionMyAccount({});
+    expect(account.metadata?.id).toBe(creatorId);
+
+    const policies = await policiesIn(server);
+    expect(rolesHeldBy(policies, creatorId)).toEqual(["owner@founded-before"]);
+    expect(policies).toHaveLength(1);
+    expect(policies[0]?.metadata?.id).toBe(
+      policyIdFor(orgRole(creatorId, "owner", "founded-before")),
+    );
+    expect(policies[0]?.status?.audit?.specAudit?.createdBy?.id).toBe(
+      creatorId,
+    );
+  });
+
+  it("an organization founded AFTER provisioning is owned through the subject read — the verifier still stamps the raw subject", async () => {
+    await createClient(
+      OrganizationCommandController,
+      transportFor(port, fakeJwt(CREATOR, "creator@example.com")),
+    ).create(organizationInput("founded-after"));
+
+    const policies = await policiesIn(server);
+    expect(rolesHeldBy(policies, creatorId)).toEqual([
+      "owner@founded-after",
+      "owner@founded-before",
+    ]);
+    expect(
+      policies.find((p) => p.spec?.resource?.id === "founded-after")?.status
+        ?.audit?.specAudit?.createdBy?.id,
+    ).toBe(creatorId);
+  });
+
+  it("a newcomer's first provisioning makes them a member of every organization; provisioning again writes nothing", async () => {
+    const asNewcomer = transportFor(
+      port,
+      fakeJwt(NEWCOMER, "newcomer@example.com"),
+    );
+    const accounts = createClient(IdentityAccountCommandController, asNewcomer);
+
+    await accounts.provisionMyAccount({});
+    const after = (await policiesIn(server)).map((p) => p.metadata?.id).sort();
+    await accounts.provisionMyAccount({});
+
+    const policies = await policiesIn(server);
+    expect(rolesHeldBy(policies, newcomerId)).toEqual([
+      "member@founded-after",
+      "member@founded-before",
+    ]);
+    expect(policies.map((p) => p.metadata?.id).sort()).toEqual(after);
+  });
+});
+
+describe("built-in authorization posture (composed server, trusted-local: the operator owns what the laptop has)", () => {
+  const OPERATOR_EMAIL = "operator@example.com";
+  const operatorId = accountIdFor(localIdpIdFor(OPERATOR_EMAIL));
+  let dir: string;
+  let server: ComposedServer;
+  let port: number;
+
+  /** One boot on the describe's directory — the same database every time. */
+  async function boot(): Promise<void> {
+    server = await composeServer({
+      config: loadConfig({
+        ...baseConfig(dir),
+        STIGMER_OPERATOR_EMAIL: OPERATOR_EMAIL,
+        STIGMER_OPERATOR_NAME: "The Operator",
+      }),
+      logger: silentLogger,
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    port = await server.start();
+  }
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "iam-policy-built-in-local-"));
+    setOperatorIdentity(OPERATOR_EMAIL, "The Operator");
+    await boot();
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    resetOperatorIdentityForTests();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("an organization created over the wire is owned by the operator's account — the caller carried an email, the row names the account", async () => {
+    await createClient(
+      OrganizationCommandController,
+      transportFor(port),
+    ).create(organizationInput("laptop-org"));
+
+    const policies = await policiesIn(server);
+    expect(rolesHeldBy(policies, operatorId)).toEqual(["owner@laptop-org"]);
+    expect(policies[0]?.status?.audit?.specAudit?.createdBy?.id).toBe(
+      operatorId,
+    );
+  });
+
+  it("a second boot on the same database writes nothing — the organization already has an owner", async () => {
+    const before = (await policiesIn(server)).map((p) => p.metadata?.id);
+    await server.shutdown();
+
+    await boot();
+
+    expect((await policiesIn(server)).map((p) => p.metadata?.id)).toEqual(
+      before,
+    );
+  });
+
+  it("an owner row deleted underneath the server is written back at the next boot", async () => {
+    const [row] = await policiesIn(server);
+    expect(row?.metadata?.id).toBeDefined();
+    await server.store.deleteResource(
+      ApiResourceKind.iam_policy,
+      row?.metadata?.id ?? "",
+    );
+    expect(await policiesIn(server)).toEqual([]);
+    await server.shutdown();
+
+    await boot();
+
+    expect(rolesHeldBy(await policiesIn(server), operatorId)).toEqual([
+      "owner@laptop-org",
+    ]);
+  });
+});