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

package/src/pipeline/apiresource-meta.ts

@@ -8,6 +8,39 @@
  * Both editions resolve the same strings from the same proto metadata; the
  * visibility helpers mirror Cloud's VisibilityConfigResolver so the
  * cross-edition error contract is identical by construction.
+ *
+ * The contract carries TWO kind vocabularies, and this module holds one
+ * lookup for each so they are never merged:
+ *
+ *   - A resource's own `kind` field is the `kind_meta.name` ("McpServer").
+ *     `getKindEnum` reads it by canonical name (case-insensitive,
+ *     underscores ignored) and throws on an unknown value.
+ *   - An `ApiResourceRef.kind` — the IamPolicy spec's principal and
+ *     resource, the FGA object type — is the enum MEMBER name
+ *     ("mcp_server"). `kindByEnumName` reads it by the descriptor's exact
+ *     proto name and never throws (20260913.01, Q-OR-2). Exact, because the
+ *     IamPolicy id is derived from the spec's text (Q-OR-9): a lenient
+ *     match would let "Organization" and "organization" mint two rows for
+ *     one grant. Reading the descriptor's name is not deriving a spelling;
+ *     the #545 rule is about recovering kind_meta.name from an enum, which
+ *     neither lookup does. A reader asked about a kind that arrived
+ *     through this vocabulary follows its doctrine: `grantableRolesFor`
+ *     answers the empty list for the unknown kind instead of throwing,
+ *     because the kind it is asked about may have come off the wire.
+ *     `kindEnumName` is the inverse — how server code SPELLS a kind when
+ *     it builds an `ApiResourceRef` itself (the built-in role lifecycle's
+ *     cleanup refs; the organization-role specs) — so no caller reaches
+ *     for the enum's reverse index by hand.
+ *
+ * A kind's TIER meets the served EDITION in exactly one place on the
+ * server, `tierServedByEdition` / `kindServedByEdition` (20260913.01
+ * Q-OR-8; claim check C5) — the twin of the SDK's rank functions
+ * (sdk/typescript/src/resource-availability.ts), pinned equal on the whole
+ * matrix by __tests__/kind-served-by-edition.test.ts. The console reads
+ * the SDK's answer to decide what to SHOW; `checkMyPermission` reads the
+ * server's to decide what is HELD; a disagreement is a surface that
+ * appears and then fails. The enum NUMBERS are wire identifiers, never
+ * ranks (`enterprise` sits at 3 in both enums and ranks second).
  */
 import { getOption, hasOption } from "@bufbuild/protobuf";
 import type { DescEnumValue } from "@bufbuild/protobuf";
@@ -16,9 +49,12 @@ import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apires
 import {
   ApiResourceKind,
   ApiResourceKindSchema,
+  ResourceTier,
   kind_meta,
 } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { ApiResourceKindMeta } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 
 /** Go GetKindMeta: the kind_meta extension of the enum value. */
 export function getKindMeta(kind: ApiResourceKind): ApiResourceKindMeta {
@@ -55,19 +91,143 @@ export function getKindEnum(kindValue: string): ApiResourceKind {
   return kind;
 }
 
+/**
+ * Resolves an `ApiResourceRef.kind` — a kind's enum MEMBER name, exactly
+ * as the proto spells it ("organization", "identity_account") — to the
+ * enum. Anything else, including the kind_meta spelling, a different case,
+ * the empty string and the zero value's own name, is
+ * `api_resource_kind_unknown`; never a throw, because the Authorize step
+ * resolves `resource_kind_path` through this at position 1 of every chain
+ * and resolution never fails a request (authorize.ts header). See the
+ * module header for why the match is exact.
+ */
+export function kindByEnumName(value: string): ApiResourceKind {
+  return (
+    kindsByEnumName().get(value) ?? ApiResourceKind.api_resource_kind_unknown
+  );
+}
+
+/**
+ * The inverse of `kindByEnumName`: a kind spelled as an `ApiResourceRef.kind`
+ * — the descriptor's exact proto name ("organization", "identity_account").
+ * Total over the enum: the unknown kind spells itself, so a ref built from
+ * it round-trips to the unknown kind and the gate that reads it refuses
+ * the way it refuses a wire caller's garbage; never a throw.
+ */
+export function kindEnumName(kind: ApiResourceKind): string {
+  // A number that is no member (a cast from outside the enum) spells as
+  // the unknown kind, which every descriptor carries as its zero value.
+  const value =
+    kindValueDescriptor(kind) ??
+    kindValueDescriptor(ApiResourceKind.api_resource_kind_unknown);
+  return value?.name ?? "";
+}
+
 /**
  * Go DefaultVisibilityFor: blueprint kinds flagged defaults_to_org_visibility
  * get visibility_org (blueprints are shared org assets — a private default
  * would silently hide new blueprints from teammates); all others get
  * visibility_private.
  */
-export function defaultVisibilityFor(kind: ApiResourceKind): ApiResourceVisibility {
+export function defaultVisibilityFor(
+  kind: ApiResourceKind,
+): ApiResourceVisibility {
   const config = getKindMeta(kind).authorization?.visibility;
   return config?.defaultsToOrgVisibility === true
     ? ApiResourceVisibility.visibility_org
     : ApiResourceVisibility.visibility_private;
 }
 
+/**
+ * The roles a user may be granted on a resource of `kind` according to the
+ * CONTRACT — `kind_meta.authorization.grantable_roles`, the one source of
+ * "what can be granted at all" (Java AuthorizationConfigResolver
+ * .getGrantableRoles; the cloud's iam/policy/roles.ts grantableRolesFor,
+ * which this replaces at the 20260913.01 re-point). A kind that lists none
+ * is system-managed in every edition (identity_account, api_key,
+ * iam_policy, invitation, agent_execution); an edition's PolicyGrantScope
+ * (extensions/policy-grant-scope.ts) only narrows this list.
+ *
+ * Total, never a throw: the kind is an `ApiResourceRef.kind` resolved by
+ * `kindByEnumName`, so the unknown kind — the one member without
+ * `kind_meta` — is a legitimate argument and answers the empty list
+ * (module header, the second vocabulary).
+ */
+export function grantableRolesFor(
+  kind: ApiResourceKind,
+): ReadonlyArray<IamRole> {
+  const valueDesc = kindValueDescriptor(kind);
+  if (valueDesc === undefined || !hasOption(valueDesc, kind_meta)) {
+    return [];
+  }
+  return getOption(valueDesc, kind_meta).authorization?.grantableRoles ?? [];
+}
+
+/**
+ * Whether an edition serves a tier: the tier names the MINIMUM edition,
+ * the editions are ordered oss < enterprise < cloud (each composes the
+ * previous one's units), so a tier admits its own edition and every one
+ * above. An edition the server does not know (`server_edition_unspecified`)
+ * serves everything — the SDK's own fallback: an older client against a
+ * newer server hides nothing. A tier the proto forgot is treated as core
+ * for the same reason the SDK does: hiding a served kind is the worse
+ * failure.
+ */
+export function tierServedByEdition(
+  tier: ResourceTier,
+  edition: ServerEdition,
+): boolean {
+  if (edition === ServerEdition.server_edition_unspecified) {
+    return true;
+  }
+  return editionRank(edition) >= tierRank(tier);
+}
+
+/**
+ * Whether this edition serves a kind: its `kind_meta.tier` through the
+ * table above. Throws for a kind without `kind_meta` (the unknown kind):
+ * a caller that reaches this with wire input has skipped the kind
+ * refusals, and "served" for it would hide that bug.
+ */
+export function kindServedByEdition(
+  kind: ApiResourceKind,
+  edition: ServerEdition,
+): boolean {
+  return tierServedByEdition(getKindMeta(kind).tier, edition);
+}
+
+function editionRank(edition: ServerEdition): number {
+  switch (edition) {
+    case ServerEdition.oss:
+      return 1;
+    case ServerEdition.enterprise:
+      return 2;
+    case ServerEdition.cloud:
+    case ServerEdition.server_edition_unspecified:
+      return 3;
+    default: {
+      const exhaustive: never = edition;
+      throw new Error(`unknown server edition: ${String(exhaustive)}`);
+    }
+  }
+}
+
+function tierRank(tier: ResourceTier): number {
+  switch (tier) {
+    case ResourceTier.open_source:
+    case ResourceTier.resource_tier_unspecified:
+      return 1;
+    case ResourceTier.enterprise:
+      return 2;
+    case ResourceTier.cloud_only:
+      return 3;
+    default: {
+      const exhaustive: never = tier;
+      throw new Error(`unknown resource tier: ${String(exhaustive)}`);
+    }
+  }
+}
+
 /**
  * Go SupportsVisibility: PRIVATE and UNSPECIFIED are always supported (no
  * visibility grant); every other level requires the matching supports_*
@@ -134,3 +294,23 @@ function kindsByCanonicalName(): Map<string, ApiResourceKind> {
   }
   return canonicalNameCache;
 }
+
+let enumNameCache: Map<string, ApiResourceKind> | undefined;
+
+/**
+ * Every member by its descriptor name, the zero value included (it maps to
+ * itself, which is the unknown kind either way). A Map rather than the TS
+ * enum's reverse mapping, so a prototype key or a number spelled as text
+ * cannot resolve to anything.
+ */
+function kindsByEnumName(): Map<string, ApiResourceKind> {
+  if (enumNameCache === undefined) {
+    enumNameCache = new Map(
+      ApiResourceKindSchema.values.map((value) => [
+        value.name,
+        value.number as ApiResourceKind,
+      ]),
+    );
+  }
+  return enumNameCache;
+}

package/src/pipeline/interceptors/auth.ts

@@ -175,6 +175,19 @@ export function trustedLocalIdentity(): CallerIdentity {
   return trustedLocalIdentityFor(operatorIdentitySnapshot());
 }
 
+/**
+ * The identityId of the UNCONFIGURED laptop's operator — no
+ * STIGMER_OPERATOR_EMAIL, so the trust domain's one principal has no
+ * email to be named by. It is what the interceptor stamps and therefore
+ * what every audit actor on such a laptop carries as `created_by.id`; the
+ * operator account derives its subject from it (`local|system`) and the
+ * membership rules read it as "not a person" when they classify creator
+ * stamps (domain/iampolicy/membership.ts). One home (20260913.01 slice 4,
+ * Q-S4-6): a second spelling anywhere would make a stamp and its reader
+ * disagree silently.
+ */
+export const SYSTEM_OPERATOR_IDENTITY_ID = "system";
+
 /**
  * The trusted-local identity for a given operator — the one construction
  * of that principal, shared by the per-request stamp above and by the
@@ -187,7 +200,7 @@ export function trustedLocalIdentityFor(operator: {
 }): CallerIdentity {
   if (operator.email === "") {
     return {
-      identityId: "system",
+      identityId: SYSTEM_OPERATOR_IDENTITY_ID,
       callerClass: "user",
       issuer: "",
       rawToken: "",

package/src/pipeline/steps/__tests__/authorize-annotation-completeness.test.ts

@@ -20,9 +20,32 @@
  * never reach the annotation's resolution (the skip lanes resolve their
  * target in the handler through `authorizeDirect`'s override). A config
  * that names NO kind (static or by path) is outside this invariant: the
- * check is then about the kind, not the id, and today no OSS-served method
- * is shaped that way (the IamPolicy RPCs that are belong to
- * `sp.oss-organization-roles`).
+ * check is then about the kind, not the id.
+ *
+ * The IamPolicy contract is the one place that shape exists, and it is
+ * pinned here by descriptor, not by served route, so the arm turns green
+ * when the ANNOTATIONS land (sp.oss-organization-roles slice 1) and not
+ * when the service is first served (slice 5). Of its nine `rpc.config`
+ * methods: six name their target — `create`, `delete`,
+ * `listResourceAccessByPrincipal`, `getPrincipalResourceRoles` by
+ * `resource_kind_path` (the spec's `resource.kind`, a STRING the resolver
+ * reads by enum name) + `field_path`; `revokeOrgAccess` and
+ * `getPrincipalsCount` statically. `get(IamPolicyId)` names no kind BY
+ * DESIGN: its target is inside the row it loads, so it is the one
+ * load-then-authorize lane (`authorizeDirect` with the override's
+ * resourceKind + resourceId, the getByEmail precedent). The two
+ * `listAuthorized*Ids` were the open question of S1 (finding 7): an
+ * annotation with a permission and no kind resolves to an EMPTY target,
+ * which the open-source permissive Authorizer allows and the cloud's
+ * OpenFGA Authorizer denies for every caller — the #1073 class this
+ * invariant cannot see. Ruled at slice 1 (2026-09-13, T01_1_review.md
+ * Q-OR-2): `listAuthorizedPrincipalIds` HAS a resource and names it (the
+ * same `can_view_access` target `listResourceAccessByPrincipal` enforces
+ * for the same question); `listAuthorizedResourceIds` has a principal and
+ * no resource, so it is an `is_skip_authorization` lane whose handler
+ * enforces `checkAuthorization`'s principal-trust rule (a user only for
+ * themselves; machine and internal for anyone) — a dead `can_view_access`
+ * config would have been exactly the kind-less shape this file guards.
  *
  * The mutation arms prove the check bites over the same function.
  */
@@ -41,6 +64,8 @@ import {
   is_public,
   is_skip_authorization,
 } from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
+import { IamPolicyCommandController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/command_pb";
+import { IamPolicyQueryController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/query_pb";
 
 import { loadConfig } from "../../../boot/config.js";
 import { composeServer } from "../../../boot/compose.js";
@@ -151,6 +176,51 @@ describe("authorization annotations name where the resource id comes from", () =
   });
 });
 
+describe("the IamPolicy contract names its targets (sp.oss-organization-roles slice 1, read by descriptor)", () => {
+  const targets = annotationTargets([
+    IamPolicyCommandController,
+    IamPolicyQueryController,
+  ]);
+  const byName = new Map(
+    targets.map((t) => [t.method.split("/")[1] ?? t.method, t]),
+  );
+
+  it.each([
+    "create",
+    "delete",
+    "revokeOrgAccess",
+    "listResourceAccessByPrincipal",
+    "getPrincipalResourceRoles",
+    "getPrincipalsCount",
+    "listAuthorizedPrincipalIds",
+  ])("%s names a resource kind AND where its id comes from", (method) => {
+    const target = byName.get(method);
+    expect(target, `${method} carries rpc.config`).toBeDefined();
+    expect(target?.namesKind, `${method} names a kind`).toBe(true);
+    expect(target?.namesId, `${method} names its id`).toBe(true);
+  });
+
+  it("get names no kind — the one load-then-authorize lane, its target inside the row", () => {
+    const get = byName.get("get");
+    expect(get, "get carries rpc.config").toBeDefined();
+    expect(get?.namesKind).toBe(false);
+    expect(get?.skipsResolution).toBe(false);
+  });
+
+  it("listAuthorizedResourceIds carries NO rpc.config and skips — its trust rule is the handler's (finding 7)", () => {
+    // Read the descriptor directly: `annotationTargets` lists only
+    // config-carrying methods, and this one must have left that set.
+    const method = IamPolicyQueryController.method.listAuthorizedResourceIds;
+    expect(byName.has("listAuthorizedResourceIds")).toBe(false);
+    expect(hasOption(method, rpcAuthorizationConfig)).toBe(false);
+    expect(getOption(method, is_skip_authorization)).toBe(true);
+  });
+
+  it("the invariant reports none of them once slice 1 lands", () => {
+    expect(unresolvableTargets(targets)).toEqual([]);
+  });
+});
+
 describe("the check bites (mutation proofs over the same function)", () => {
   const shaped = (overrides: Partial<AnnotationTarget>): AnnotationTarget => ({
     method: "x.v1.Query/probe",

package/src/pipeline/steps/__tests__/authorize.test.ts

@@ -4,9 +4,11 @@
  * annotation's byte-pinned error_msg; unavailable → INTERNAL, never a
  * softened denial), the skip arms (internal caller class, is_public,
  * is_skip_authorization, no-config methods), check-target resolution
- * (field_path, static resource_id, absent field = empty id — never a
- * throw), and the mid-chain resolved-id pattern the traced ListVersions
- * handlers port onto.
+ * (field_path, static resource_id, absent field = empty id, a string
+ * resource_kind_path resolved by enum name with an unknown name = the
+ * unknown kind — never a throw), the direct-handler override in both its
+ * shapes (a server-side id; a server-side kind AND id), and the mid-chain
+ * resolved-id pattern the traced ListVersions handlers port onto.
  */
 import { describe, expect, it } from "vitest";
 import { create } from "@bufbuild/protobuf";
@@ -17,6 +19,7 @@ import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb"
 import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
 import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { IamPolicyCommandController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/command_pb";
+import { IamPolicyQueryController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/query_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -37,9 +40,7 @@ import {
 } from "../authorize.js";
 
 /** Awaits the rejection and returns it as a ConnectError. */
-async function captureError(
-  run: () => Promise<void>,
-): Promise<ConnectError> {
+async function captureError(run: () => Promise<void>): Promise<ConnectError> {
   try {
     await run();
   } catch (error) {
@@ -290,6 +291,75 @@ describe("check-target resolution (never a throw — byte-identity)", () => {
       },
     ]);
   });
+
+  // 20260913.01 (Q-OR-2): the IamPolicy RPCs name their target inside the
+  // request as a STRING kind (`ApiResourceRef.kind`, "organization"), so
+  // `resource_kind_path` resolves a string through the kind enum's names.
+  // The option had no user before this entry; a numeric field still works.
+  it("resource_kind_path over a string field resolves through the kind enum's names (IamPolicy create)", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyCommandController.method.create;
+    const step = newAuthorizeStep(method, authorizer);
+    const ctx = new RequestContext(
+      method.input,
+      create(method.input, {
+        principal: { kind: "identity_account", id: "ida_alice" },
+        relation: "member",
+        resource: { kind: "organization", id: "acme" },
+      }),
+      testCallerIdentity(),
+    );
+    await step.execute(ctx);
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_grant_access,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
+
+  it("an unknown kind name resolves to the unknown kind — never a throw; the Authorizer owns the decision", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyCommandController.method.create;
+    const step = newAuthorizeStep(method, authorizer);
+    const ctx = new RequestContext(
+      method.input,
+      create(method.input, {
+        principal: { kind: "identity_account", id: "ida_alice" },
+        relation: "member",
+        resource: { kind: "spaceship", id: "acme" },
+      }),
+      testCallerIdentity(),
+    );
+    await expect(step.execute(ctx)).resolves.toBeUndefined();
+    expect(checks[0]?.resourceKind).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+    expect(checks[0]?.resourceId).toBe("acme");
+  });
+
+  it("revokeOrgAccess names the organization statically and its id by field_path (organization_id)", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyCommandController.method.revokeOrgAccess;
+    const step = newAuthorizeStep(method, authorizer);
+    const ctx = new RequestContext(
+      method.input,
+      create(method.input, {
+        identityAccountId: "ida_alice",
+        organizationId: "acme",
+      }),
+      testCallerIdentity(),
+    );
+    await step.execute(ctx);
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_grant_access,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
 });
 
 describe("authorizeDirect (the direct-handler arm, C2 Stage 4)", () => {
@@ -348,6 +418,49 @@ describe("authorizeDirect (the direct-handler arm, C2 Stage 4)", () => {
     ]);
   });
 
+  // 20260913.01 (Q-OR-2): the IamPolicy `get(IamPolicyId)` lane. Its
+  // annotation names a permission and NO kind, because the target is the
+  // loaded row's resource — kind AND id are server-side state. The
+  // override carries both; the annotation still owns the permission and
+  // the copy.
+  it("the target override may carry the resource KIND too — the IamPolicy get lane", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyQueryController.method.get;
+    await authorizeDirect(
+      method,
+      authorizer,
+      testCallerIdentity(),
+      create(method.input, { value: "iamp_01row" }),
+      { resourceKind: ApiResourceKind.organization, resourceId: "acme" },
+    );
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_view_access,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
+
+  it("an override with the id alone leaves the annotation's kind in place — the completeOAuthConnect lane is unchanged", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyQueryController.method.get;
+    // A kind-less annotation plus an id-only override: the kind stays
+    // unknown, exactly what the annotation says. The lane that needs a
+    // kind must say so; nothing is inferred.
+    await authorizeDirect(
+      method,
+      authorizer,
+      testCallerIdentity(),
+      create(method.input, { value: "iamp_01row" }),
+      { resourceId: "acme" },
+    );
+    expect(checks[0]?.resourceKind).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+    expect(checks[0]?.resourceId).toBe("acme");
+  });
+
   it("the ruling-Q1 not-found arm maps identically from the direct entry", async () => {
     const { authorizer } = fakeAuthorizer({ kind: "not-found" });
     const error = await authorizeDirect(
@@ -438,18 +551,30 @@ describe("authorizeResolvedResource (the mid-chain resolved-id pattern, 20260830
       ),
     );
     expect(err.code).toBe(Code.PermissionDenied);
-    expect(err.rawMessage).toBe("unauthorized to view workflow version history");
+    expect(err.rawMessage).toBe(
+      "unauthorized to view workflow version history",
+    );
   });
 
   it("deny without lane copy falls back to the reason, then the shared fallback", async () => {
     const reasoned = fakeAuthorizer({ kind: "deny", reason: "because" });
     const err1 = await captureError(() =>
-      authorizeResolvedResource(reasoned.authorizer, testCallerIdentity(), check, ""),
+      authorizeResolvedResource(
+        reasoned.authorizer,
+        testCallerIdentity(),
+        check,
+        "",
+      ),
     );
     expect(err1.rawMessage).toBe("because");
     const bare = fakeAuthorizer({ kind: "deny", reason: "" });
     const err2 = await captureError(() =>
-      authorizeResolvedResource(bare.authorizer, testCallerIdentity(), check, ""),
+      authorizeResolvedResource(
+        bare.authorizer,
+        testCallerIdentity(),
+        check,
+        "",
+      ),
     );
     expect(err2.rawMessage).toBe("permission denied");
   });

package/src/pipeline/steps/__tests__/derived-id.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Pins `derivedId`, the one encoder behind every id a kind derives from its
+ * natural key instead of minting (metadata.proto's `id` comment: a direct
+ * IdentityAccount from its subject, an IamPolicy from its triple; the
+ * Organization's slug needs no encoding). Lifted from the identity-account
+ * domain in 20260913.01 slice 2 so the second derived id did not carry a
+ * second copy of the grammar.
+ *
+ * The vectors here are the two domains' golden vectors restated through
+ * the shared function: `accountIdFor` and `policyIdFor` must equal
+ * `derivedId(prefix, text)` over their canonical text, and those domain
+ * tests pin the wire-adjacent constants. A change to the encoding
+ * re-addresses every derived row open source ever wrote.
+ */
+import { describe, expect, it } from "vitest";
+
+import { derivedId } from "../defaults.js";
+
+const CROCKFORD_26 = /^[0-9abcdefghjkmnpqrstvwxyz]{26}$/;
+
+describe("derivedId — prefix, underscore, the top 130 bits of sha256 as 26 Crockford chars", () => {
+  it("matches the identity-account golden vector", () => {
+    // accountIdFor("auth0|user123") as pinned in identityaccount/__tests__/constants.test.ts.
+    expect(derivedId("ida", "auth0|user123")).toBe(
+      "ida_wtr3jcf281yfk9xx61kj59fsme",
+    );
+  });
+
+  it("matches the IamPolicy golden vector over the canonical triple text", () => {
+    expect(
+      derivedId(
+        "iamp",
+        "identity_account:ida_wtr3jcf281yfk9xx61kj59fsme#@organization:acme#admin",
+      ),
+    ).toBe("iamp_vkbjb6nvqm77vtwnr2bj0x95f9");
+  });
+
+  it("has the minted id's shape whatever the prefix, so nothing downstream learns a second grammar", () => {
+    const id = derivedId("xyz", "anything");
+    expect(id.startsWith("xyz_")).toBe(true);
+    expect(id.slice("xyz_".length)).toMatch(CROCKFORD_26);
+  });
+
+  it("is a pure function of prefix and text: equal inputs, equal ids; a changed byte, a changed id", () => {
+    expect(derivedId("ida", "same")).toBe(derivedId("ida", "same"));
+    expect(derivedId("ida", "same")).not.toBe(derivedId("ida", "same "));
+    expect(derivedId("ida", "same")).not.toBe(derivedId("iamp", "same"));
+  });
+});