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

package/src/pipeline/steps/authorize.ts

@@ -31,9 +31,13 @@
  * Resolution never throws: an unresolvable `field_path` yields an empty
  * resource id and an unresolvable `resource_kind_path` yields the unknown
  * kind — the check still reaches the Authorizer, which owns the decision.
- * A thrown resolution would be a NEW wire behavior on requests that are
- * legal today (byte-identity forbids it); an implementation that wants to
- * refuse empty ids does so as a deny, visibly.
+ * A `resource_kind_path` may point at an `ApiResourceKind` field or at a
+ * string carrying a kind's enum member name (an `ApiResourceRef.kind`, the
+ * IamPolicy RPCs' spec-named target; 20260913.01 Q-OR-2); a string that is
+ * not exactly a member name is the unknown kind, which an enforcing
+ * authorizer denies. A thrown resolution would be a NEW wire behavior on
+ * requests that are legal today (byte-identity forbids it); an
+ * implementation that wants to refuse empty ids does so as a deny, visibly.
  *
  * `authorizeDirect` is the SAME evaluation exported for the direct
  * handlers — the config-annotated methods that deliberately run no
@@ -42,11 +46,16 @@
  * two entry shapes; a direct handler calls it after its own input
  * validation and before any load or side effect, mirroring the Java
  * edition's validate → authorize handler order (C2 Stage 4 ruling,
- * 20260827.10). The optional target override serves the one lane whose
- * true target is server-side state rather than caller input
- * (completeOAuthConnect authorizes the PENDING RECORD's server id — a
- * caller-supplied id would be a confused-deputy hole, the Java
- * McpServerCompleteOAuthConnectHandler discipline).
+ * 20260827.10). The optional target override serves the lanes whose true
+ * target is server-side state rather than caller input, in two shapes:
+ * a server-side ID under the annotation's static kind (completeOAuthConnect
+ * authorizes the PENDING RECORD's server id — a caller-supplied id would
+ * be a confused-deputy hole, the Java McpServerCompleteOAuthConnectHandler
+ * discipline; getByEmail/getByIdpId authorize the account they looked up),
+ * and a server-side kind AND id (the IamPolicy `get`, whose annotation
+ * names no kind because the target is the loaded row's resource). The
+ * annotation keeps owning the permission, the copy and the skip arms in
+ * both shapes; only the target is the handler's.
  */
 import { Code, ConnectError } from "@connectrpc/connect";
 import type { DescMethod, DescMessage, Message } from "@bufbuild/protobuf";
@@ -66,7 +75,7 @@ import type {
   AuthzDecision,
 } from "../../extensions/authorizer.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
-import { getKindName } from "../apiresource-meta.js";
+import { getKindName, kindByEnumName } from "../apiresource-meta.js";
 import { internalError, notFoundError } from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
@@ -115,12 +124,16 @@ export function newAuthorizeStep<Desc extends DescMessage>(
 }
 
 /**
- * The one lane whose authorization target is server-side state rather
- * than a request field (see the module header). `resourceId` replaces the
- * annotation's `field_path`/`resource_id` resolution; everything else —
- * skip arms, kind, permission, copy — still comes from the annotation.
+ * The lanes whose authorization target is server-side state rather than a
+ * request field (see the module header). `resourceId` replaces the
+ * annotation's `field_path`/`resource_id` resolution; `resourceKind`, when
+ * given, replaces its `resource_kind`/`resource_kind_path` resolution — the
+ * lane whose annotation names no kind because the kind is inside the row
+ * it loaded. Everything else — skip arms, permission, copy — still comes
+ * from the annotation.
  */
 export interface AuthorizeTargetOverride {
+  readonly resourceKind?: ApiResourceKind;
   readonly resourceId: string;
 }
 
@@ -156,7 +169,8 @@ export async function authorizeDirect(
     identity,
     {
       permission: config.permission,
-      resourceKind: resolveResourceKind(input, config),
+      resourceKind:
+        override?.resourceKind ?? resolveResourceKind(input, config),
       resourceId: override?.resourceId ?? resolveResourceId(input, config),
     },
     config.errorMsg,
@@ -189,7 +203,7 @@ export async function authorizeResolvedResource(
   if (identity.callerClass === "internal") {
     return;
   }
-  const decision = await runAuthorizer(authorizer, identity, check);
+  const decision = await evaluateAuthorizer(authorizer, identity, check);
   switch (decision.kind) {
     case "allow":
       return;
@@ -234,9 +248,13 @@ export async function authorizeResolvedResource(
 /**
  * An Authorizer that THROWS is an evaluation failure by definition —
  * normalized into the unavailable arm so a buggy implementation can never
- * soften an outage into a denial by accident.
+ * soften an outage into a denial by accident. Exported for the one lane
+ * that needs the DECISION rather than the wire mapping: `checkMyPermission`
+ * answers a boolean (allow → true, deny and not-found → false) and maps
+ * only `unavailable` to the wire, through the same INTERNAL copy
+ * (20260913.01, Q-S5-3).
  */
-async function runAuthorizer(
+export async function evaluateAuthorizer(
   authorizer: Authorizer,
   identity: CallerIdentity,
   check: AuthzCheck,
@@ -251,7 +269,10 @@ async function runAuthorizer(
   }
 }
 
-/** Static kind, or the resource_kind_path read, or unknown — never a throw. */
+/**
+ * Static kind, or the resource_kind_path read — an enum field as its
+ * number, a string as an enum member name — or unknown. Never a throw.
+ */
 function resolveResourceKind(
   input: Message,
   config: RpcAuthorizationConfig,
@@ -260,9 +281,13 @@ function resolveResourceKind(
     return config.resourceKind;
   }
   const value = resolveDotPath(input, config.resourceKindPath);
-  return typeof value === "number"
-    ? (value as ApiResourceKind)
-    : ApiResourceKind.api_resource_kind_unknown;
+  if (typeof value === "number") {
+    return value as ApiResourceKind;
+  }
+  if (typeof value === "string") {
+    return kindByEnumName(value);
+  }
+  return ApiResourceKind.api_resource_kind_unknown;
 }
 
 /** Static resource_id, or the field_path read, or "" — never a throw. */

package/src/pipeline/steps/defaults.ts

@@ -14,7 +14,19 @@
  * setAuditFieldsForUpdate call site declares which slot it owns —
  * SpecAudit for definition changes (search recency, version "pushed at"),
  * StatusAudit for operational changes (Recents, lifecycle metadata).
+ *
+ * This module is also the one home of how an id is SPELLED. `generateId`
+ * mints `{prefix}_{ulid}`; `derivedId` is its sibling for the kinds
+ * metadata.proto names as deriving their id from a natural key instead
+ * (a direct IdentityAccount from its issuer subject, an IamPolicy from its
+ * triple): `{prefix}_` + the top 130 bits of sha256 over the key's
+ * canonical text as 26 lowercase Crockford-base32 characters. The two
+ * shapes are indistinguishable on the wire, so nothing downstream learns
+ * a second grammar, and the primary key becomes the one home of "one row
+ * per natural key" without a secondary index or a scan.
  */
+import { createHash } from "node:crypto";
+
 import { create, clone } from "@bufbuild/protobuf";
 import type { DescMessage, Message } from "@bufbuild/protobuf";
 import { reflect } from "@bufbuild/protobuf/reflect";
@@ -353,3 +365,33 @@ function setAuditSlotReflect(
 export function generateId(prefix: string): string {
   return `${prefix}_${ulid().toLowerCase()}`;
 }
+
+/** Crockford base32, lowercased — the alphabet every minted ULID id uses. */
+const CROCKFORD_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+const DERIVED_ID_CHARS = 26;
+const DERIVED_ID_BITS = BigInt(DERIVED_ID_CHARS * 5);
+const SHA256_BITS = 256n;
+
+/**
+ * The derived id of a kind whose id is a function of its natural key
+ * (metadata.proto `id`): `{prefix}_` + the top 130 bits of
+ * sha256(canonicalText) as 26 lowercase Crockford-base32 characters. Pure
+ * and total; the CALLER owns what `canonicalText` may be (the domains
+ * refuse an empty subject or an ambiguous triple before hashing), and the
+ * domains' golden vectors are the wire-adjacent pin — a change here
+ * re-addresses every derived row open source ever wrote.
+ */
+export function derivedId(prefix: string, canonicalText: string): string {
+  const digest = createHash("sha256").update(canonicalText, "utf8").digest();
+  let bits = 0n;
+  for (const byte of digest) {
+    bits = (bits << 8n) | BigInt(byte);
+  }
+  let top = bits >> (SHA256_BITS - DERIVED_ID_BITS);
+  let encoded = "";
+  for (let i = 0; i < DERIVED_ID_CHARS; i++) {
+    encoded = CROCKFORD_ALPHABET[Number(top & 31n)] + encoded;
+    top >>= 5n;
+  }
+  return `${prefix}_${encoded}`;
+}

package/src/store/__tests__/port-contract.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Pins the port-contract runner (../port-contract.ts), the scaffolding every
+ * domain store port's kit is built on (identity-account since 20260911.11;
+ * IamPolicy since 20260913.01 slice 2, when the scaffolding was lifted out
+ * of the first kit so the second did not copy it):
+ *
+ *   - every case makes a FRESH fixture, runs its body over it, and cleans
+ *     up — in that order, once each;
+ *   - a failing body is the failure reported: a cleanup that fails after
+ *     a failed body must not replace the assertion that matters with a
+ *     teardown detail;
+ *   - a cleanup that fails after a PASSING body is a real failure and
+ *     propagates;
+ *   - the case list keeps the declared names in the declared order, so a
+ *     consumer's pinned name list is a faithful diff of the contract.
+ */
+import { describe, expect, it } from "vitest";
+
+import { portContractCases } from "../port-contract.js";
+import type { PortContractFixture } from "../port-contract.js";
+
+interface Probe {
+  readonly label: string;
+}
+
+type ProbeFixture = PortContractFixture<Probe>;
+
+function fixtureFactory(
+  log: string[],
+  options: { readonly failCleanup?: boolean } = {},
+): () => Promise<ProbeFixture> {
+  let made = 0;
+  return async () => {
+    made += 1;
+    const label = `fixture-${made}`;
+    log.push(`make ${label}`);
+    return {
+      store: { label },
+      disconnect: async () => {
+        log.push(`disconnect ${label}`);
+      },
+      cleanup: async () => {
+        log.push(`cleanup ${label}`);
+        if (options.failCleanup === true) {
+          throw new Error(`cleanup of ${label} failed`);
+        }
+      },
+    };
+  };
+}
+
+describe("portContractCases", () => {
+  it("keeps the declared names in the declared order", () => {
+    const cases = portContractCases<Probe>(
+      [
+        ["first line", async () => {}],
+        ["second line", async () => {}],
+      ],
+      fixtureFactory([]),
+    );
+    expect(cases.map((contractCase) => contractCase.name)).toEqual([
+      "first line",
+      "second line",
+    ]);
+  });
+
+  it("makes a fresh fixture per case, runs the body over it, then cleans up — once each", async () => {
+    const log: string[] = [];
+    const cases = portContractCases<Probe>(
+      [
+        [
+          "a",
+          async ({ store }) => {
+            log.push(`body over ${store.label}`);
+          },
+        ],
+        [
+          "b",
+          async ({ store }) => {
+            log.push(`body over ${store.label}`);
+          },
+        ],
+      ],
+      fixtureFactory(log),
+    );
+    for (const contractCase of cases) {
+      await contractCase.run();
+    }
+    expect(log).toEqual([
+      "make fixture-1",
+      "body over fixture-1",
+      "cleanup fixture-1",
+      "make fixture-2",
+      "body over fixture-2",
+      "cleanup fixture-2",
+    ]);
+  });
+
+  it("reports the body's failure, not the cleanup's, when both fail", async () => {
+    const log: string[] = [];
+    const [only] = portContractCases<Probe>(
+      [
+        [
+          "assertion loses to nothing",
+          async () => {
+            throw new Error("the assertion that matters");
+          },
+        ],
+      ],
+      fixtureFactory(log, { failCleanup: true }),
+    );
+    await expect(only?.run()).rejects.toThrow("the assertion that matters");
+    expect(log).toEqual(["make fixture-1", "cleanup fixture-1"]);
+  });
+
+  it("a cleanup failure after a passing body is a real failure", async () => {
+    const [only] = portContractCases<Probe>(
+      [["passes", async () => {}]],
+      fixtureFactory([], { failCleanup: true }),
+    );
+    await expect(only?.run()).rejects.toThrow("cleanup of fixture-1 failed");
+  });
+});

package/src/store/port-contract.ts

@@ -0,0 +1,102 @@
+/**
+ * The port-contract runner — the scaffolding every domain store PORT's
+ * contract kit is built on (identity-account's store-contract.ts since
+ * 20260911.11 A11; IamPolicy's since 20260913.01 slice 2, when this was
+ * lifted out of the first kit so the second did not carry a copy).
+ *
+ * A port kit is a list of named cases a DRIVER's test iterates: open
+ * source runs them over its adapter on sqlite and Postgres, a composition
+ * runs the same list over the store it registers as a driver, so "the port
+ * holds" is one statement proven per driver, never restated per
+ * repository. This module owns the part every kit shares and no kit should
+ * restate: a FRESH fixture per case, the body run over it, cleanup after,
+ * and the rule that a failing body is the failure reported (a cleanup that
+ * fails after a failed body must not replace the assertion that matters
+ * with a teardown detail; a cleanup that fails after a passing body is a
+ * real failure).
+ *
+ * Shape. The package's precedent is store/__tests__/store-contract.ts —
+ * `describeStoreContract(makeFixture)` over the generic Store, a vitest
+ * `describe`. A port kit is consumed by ANOTHER package's tests through the
+ * published barrel, 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.
+ *
+ * `disconnect` is the one escape hatch a port cannot express: a port has
+ * no lifecycle by design (a composition owns its store's), yet "an outage
+ * never reads as not-found" is the line that matters most, so a fixture
+ * cuts its store from the database and the kit asserts that the fault
+ * propagates. `cleanup` must tolerate a disconnected store.
+ */
+
+/** One fresh, isolated store per case, plus the one escape hatch the port cannot express. */
+export interface PortContractFixture<Port> {
+  readonly store: Port;
+  /**
+   * 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>;
+}
+
+export interface PortContractCase {
+  /** 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 runner owns the fixture's lifecycle around it. */
+export type PortContractBody<Port> = (
+  fixture: PortContractFixture<Port>,
+) => Promise<void>;
+
+/** A kit's declaration: the contract line and the body that proves it. */
+export type PortContractDeclaration<Port> = readonly [
+  name: string,
+  body: PortContractBody<Port>,
+];
+
+/**
+ * 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<Port>(
+  makeFixture: () => Promise<PortContractFixture<Port>>,
+  body: PortContractBody<Port>,
+): 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 kit's declarations as runnable cases over `makeFixture`, one fresh fixture per case, in declared order. */
+export function portContractCases<Port>(
+  declarations: ReadonlyArray<PortContractDeclaration<Port>>,
+  makeFixture: () => Promise<PortContractFixture<Port>>,
+): ReadonlyArray<PortContractCase> {
+  return declarations.map(([name, body]) => ({
+    name,
+    run: () => withFixture(makeFixture, body),
+  }));
+}