@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/dist/domain/iampolicy/constants.js

@@ -0,0 +1,203 @@
+/**
+ * IamPolicy domain constants (20260913.01, T01_0_plan.md §3a;
+ * T01_1_review.md Q-OR-6b, Q-OR-9; slice 2 ruling Q-S2-1): the derived
+ * policy id and the one spelling of a triple it hashes, the kinds the
+ * legacy-creator rule scans, and the byte-pinned wire copy.
+ *
+ * The derived id (Q-OR-9). A policy's id is a pure function of its triple:
+ * `iamp_` + `derivedId` (pipeline/steps/defaults.ts, the encoder shared
+ * with the identity account) over the triple's canonical text. The text
+ * IS the tuple notation the contract's own comment documents
+ * (`principal.kind:principal.id#principal.relation@resource.kind:resource.id#relation`,
+ * spec.proto), the principal's `#` present even when its qualifier is
+ * empty, so the natural key has one spelling and the primary key is the
+ * one home of "one row per triple" in open source: two concurrent grants
+ * converge by primary key with no secondary index and no scan. The golden
+ * vectors in __tests__/constants.test.ts are wire-adjacent contract: a
+ * change here re-addresses every policy open source ever wrote.
+ *
+ * The text's one weakness (Q-S2-1): `ApiResourceRef` fields carry no
+ * character pattern, so an id or relation holding one of the three
+ * delimiters could spell another triple's text (`a#b` with an empty
+ * qualifier and `a` with qualifier `b#` read alike). `malformedTripleField`
+ * names such a field; `policyIdFor` refuses to hash such a spec; the grant
+ * path turns the same check into INVALID_ARGUMENT before any read or write.
+ * No legitimate reference carries a delimiter: every kind is an enum member
+ * name, every id a `prefix_ulid`, a slug or the public wildcard `*`, every
+ * relation an FGA relation name — and OpenFGA itself rejects `:` and `#`
+ * in ids, so the cloud loses nothing it could ever have written.
+ *
+ * `BLUEPRINT_KINDS` (Q-OR-6b) is the legacy-creator rule's whole scan: the
+ * kinds an admin authors. Sessions, executions, keys and memories are
+ * personal and stay with their creator by DD-002 rule 2; they never appear
+ * here.
+ *
+ * The copy moved from the cloud's iam/policy/handlers.ts as-is: the CLI,
+ * console and SDK show these sentences verbatim, so they are contract. The
+ * new sentences are the two edition refusals (the federation shape), the
+ * unknown permission, the unknown principal kind (the resource sentence's
+ * shape) and the malformed triple.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { derivedId } from "../../pipeline/steps/defaults.js";
+/** The kind's id prefix (kind_meta `iam_policy.id_prefix`). */
+export const POLICY_ID_PREFIX = "iamp";
+/**
+ * The proto's `api_version` const (api.proto). The cloud's Java-era rows
+ * carry `iam.stigmer.com/v1` and are read as they are (Q-OR-9); every row
+ * this domain writes carries the contract's value.
+ */
+export const IAM_POLICY_API_VERSION = "iam.stigmer.ai/v1";
+export const IAM_POLICY_KIND = "IamPolicy";
+/** The three characters the canonical text is built from; none may appear inside a field. */
+export const TRIPLE_DELIMITERS = [":", "#", "@"];
+function completeTriple(spec) {
+    if (spec.principal === undefined || spec.resource === undefined) {
+        throw new Error("policy spec must carry principal and resource");
+    }
+    return {
+        principal: spec.principal,
+        resource: spec.resource,
+        relation: spec.relation,
+    };
+}
+/**
+ * The proto's tuple notation, the one spelling of a triple:
+ * `principal.kind:principal.id#principal.relation@resource.kind:resource.id#relation`.
+ * The principal's `#` is always present (an empty qualifier reads `#@`),
+ * so the same triple never has two texts.
+ */
+export function canonicalTripleText(spec) {
+    const { principal, resource, relation } = completeTriple(spec);
+    return `${principal.kind}:${principal.id}#${principal.relation}@${resource.kind}:${resource.id}#${relation}`;
+}
+/**
+ * The first field, in the text's order, holding a delimiter — or
+ * `undefined` for a well-formed triple. Named in the proto's field paths so
+ * a refusal tells the caller exactly what to fix. Total over a spec
+ * missing a reference: that is `completeTriple`'s refusal, not this one.
+ */
+export function malformedTripleField(spec) {
+    const fields = [
+        ["principal.kind", spec.principal?.kind ?? ""],
+        ["principal.id", spec.principal?.id ?? ""],
+        ["principal.relation", spec.principal?.relation ?? ""],
+        ["resource.kind", spec.resource?.kind ?? ""],
+        ["resource.id", spec.resource?.id ?? ""],
+        ["relation", spec.relation],
+    ];
+    for (const [path, value] of fields) {
+        if (TRIPLE_DELIMITERS.some((delimiter) => value.includes(delimiter))) {
+            return path;
+        }
+    }
+    return undefined;
+}
+/**
+ * The derived policy id of a triple. Pure; refuses a spec missing either
+ * reference (a triple is the whole key) and a spec whose text would be
+ * ambiguous (Q-S2-1) — both are the assert behind the grant path's gate,
+ * which is where a caller hears INVALID_ARGUMENT.
+ */
+export function policyIdFor(spec) {
+    const text = canonicalTripleText(spec);
+    const malformed = malformedTripleField(spec);
+    if (malformed !== undefined) {
+        throw new Error(malformedTripleMessage(malformed));
+    }
+    return derivedId(POLICY_ID_PREFIX, text);
+}
+/**
+ * The kinds an admin authors — the legacy-creator rule's scan (Q-OR-6b),
+ * in registry order. A caller who created one of these idp-shaped, before
+ * an account existed, becomes admin on first sign-in.
+ */
+export const BLUEPRINT_KINDS = [
+    ApiResourceKind.agent,
+    ApiResourceKind.workflow,
+    ApiResourceKind.skill,
+    ApiResourceKind.mcp_server,
+    ApiResourceKind.environment,
+    ApiResourceKind.schedule,
+];
+/**
+ * The principal kinds a PERSON may grant a role to — the user `create`
+ * lane's grantee vocabulary (2026-09-14, session 9 ruling Q-S9-2; the
+ * security read's finding 41). A role names a person, so the one grantee
+ * is the identity account. A row whose principal is a RESOURCE
+ * (`organization:A#organization@platform_client:X`, `#managed_org`) is a
+ * structural link, and structural links are `bootstrapPolicy`'s — the
+ * platform's own lane, which skips role validation by design.
+ *
+ * Why the rule is load-bearing: the read side treats every principal
+ * outside this vocabulary as a structural parent (`findScopeTuple`,
+ * resource-store.ts, which derives its exclusion FROM this constant so the
+ * two cannot drift), and the hierarchy walk follows it. Without the arm, a
+ * person with `can_grant_access` on organization B could write
+ * `organization:A#member@organization:B` and B's Members page, asked for
+ * inherited access, would list A's people. The cloud's `create` had the
+ * same gap; the store's exclusion also keeps the cloud's Java-era `team`,
+ * which is not an ApiResourceKind and so no wire spec can name.
+ */
+export const USER_GRANT_PRINCIPAL_KINDS = [
+    ApiResourceKind.identity_account,
+];
+// ---------------------------------------------------------------------------
+// Byte-pinned copy (the cloud handlers' sentences, moved as-is).
+// ---------------------------------------------------------------------------
+/** get on a missing policy (NOT_FOUND). */
+export function policyNotFoundMessage(id) {
+    return `IAM policy not found: ${id}`;
+}
+/** A grant on a kind whose kind_meta lists no grantable roles (INVALID_ARGUMENT, every edition). */
+export function noGrantableRolesMessage(kind) {
+    return `No roles can be granted on resource kind '${kind}'. Role assignments for this resource kind are system-managed.`;
+}
+/** A role the kind does not list (INVALID_ARGUMENT); the grantable list in kind_meta order. */
+export function roleNotGrantableMessage(role, kind, grantable) {
+    return `Role '${role}' cannot be granted on resource kind '${kind}'. Grantable roles: [${grantable.join(", ")}]`;
+}
+/** checkMyPermission for a caller with no identity (UNAUTHENTICATED). */
+export const AUTHENTICATION_REQUIRED_MESSAGE = "Authentication required to check permissions";
+/**
+ * A spec whose resource kind is not an ApiResourceKind member name
+ * (INVALID_ARGUMENT; the cloud's `kindFromSpecString` sentence). The grant
+ * path is where a permissive Authorizer's caller hears it; an enforcing
+ * Authorizer denies the unknown kind at position 1 first (slice 1, ruling 2).
+ */
+export function unknownResourceKindMessage(kind) {
+    return `Unknown resource kind: '${kind}'`;
+}
+// ---------------------------------------------------------------------------
+// New copy (this entry's refusals).
+// ---------------------------------------------------------------------------
+/**
+ * A grant on a kind outside the composed grant scope (UNIMPLEMENTED) — the
+ * federation and kind-registry degrade-by-probe posture: the sentence a
+ * person can act on, naming the editions that serve it.
+ */
+export const PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE = "per-resource access grants are served by the Enterprise and Cloud editions";
+/** The tuple-half queries on a composition without an AuthorizationQueryEngine (UNIMPLEMENTED). */
+export const AUTHORIZATION_QUERIES_UNIMPLEMENTED_MESSAGE = "authorization queries are served by the Enterprise and Cloud editions";
+/** checkMyPermission with a relation that is no IamPermission name (INVALID_ARGUMENT). */
+export function unknownPermissionMessage(relation) {
+    return `unknown permission '${relation}'`;
+}
+/** A spec whose principal kind is not an ApiResourceKind member name (INVALID_ARGUMENT). */
+export function unknownPrincipalKindMessage(kind) {
+    return `Unknown principal kind: '${kind}'`;
+}
+/**
+ * A user grant whose principal is not a person (INVALID_ARGUMENT; Q-S9-2),
+ * in the role sentence's shape: the offending kind, then the vocabulary.
+ */
+export function principalNotGrantableMessage(kind) {
+    const grantable = USER_GRANT_PRINCIPAL_KINDS.map((k) => kindEnumName(k));
+    return `Principal kind '${kind}' cannot be granted a role. Grantable principal kinds: [${grantable.join(", ")}]`;
+}
+/** A triple field holding a canonical-text delimiter (INVALID_ARGUMENT; Q-S2-1). */
+export function malformedTripleMessage(field) {
+    return `policy ${field} must not contain ':', '#' or '@'`;
+}
+//# sourceMappingURL=constants.js.map

package/dist/domain/iampolicy/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/domain/iampolicy/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,qFAAqF,CAAC;AAMtH,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAE7D,+DAA+D;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,iBAAiB,GAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AASxE,SAAS,cAAc,CAAC,IAAmB;IACzC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAmB;IACrD,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,GAAG,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,IAAI,SAAS,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,EAAE,IAAI,QAAQ,EAAE,CAAC;AAC/G,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAmB;IACtD,MAAM,MAAM,GAA0D;QACpE,CAAC,gBAAgB,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC;QAC9C,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC;QAC1C,CAAC,oBAAoB,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,IAAI,EAAE,CAAC;QACtD,CAAC,eAAe,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC;QAC5C,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC;KAC5B,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,SAAS,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAmC;IAC7D,eAAe,CAAC,KAAK;IACrB,eAAe,CAAC,QAAQ;IACxB,eAAe,CAAC,KAAK;IACrB,eAAe,CAAC,UAAU;IAC1B,eAAe,CAAC,WAAW;IAC3B,eAAe,CAAC,QAAQ;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAmC;IACxE,eAAe,CAAC,gBAAgB;CACjC,CAAC;AAEF,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,2CAA2C;AAC3C,MAAM,UAAU,qBAAqB,CAAC,EAAU;IAC9C,OAAO,yBAAyB,EAAE,EAAE,CAAC;AACvC,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,6CAA6C,IAAI,gEAAgE,CAAC;AAC3H,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,uBAAuB,CACrC,IAAY,EACZ,IAAY,EACZ,SAAgC;IAEhC,OAAO,SAAS,IAAI,yCAAyC,IAAI,wBAAwB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACnH,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,MAAM,+BAA+B,GAC1C,8CAA8C,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,OAAO,2BAA2B,IAAI,GAAG,CAAC;AAC5C,CAAC;AAED,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,yCAAyC,GACpD,4EAA4E,CAAC;AAE/E,mGAAmG;AACnG,MAAM,CAAC,MAAM,2CAA2C,GACtD,uEAAuE,CAAC;AAE1E,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IACvD,OAAO,uBAAuB,QAAQ,GAAG,CAAC;AAC5C,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,OAAO,4BAA4B,IAAI,GAAG,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAY;IACvD,MAAM,SAAS,GAAG,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,mBAAmB,IAAI,2DAA2D,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACnH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,UAAU,KAAK,mCAAmC,CAAC;AAC5D,CAAC"}

package/dist/domain/iampolicy/controller.d.ts

@@ -0,0 +1,29 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import type { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import type { Logger } from "../../boot/logger.js";
+import type { AuthorizationQueryEngine } from "../../extensions/authorization-queries.js";
+import type { Authorizer } from "../../extensions/authorizer.js";
+import type { PolicyGrantScope } from "../../extensions/policy-grant-scope.js";
+import type { AccountsByCaller } from "../identityaccount/resolve.js";
+import type { AccountsByIds } from "./display-resolver.js";
+import type { IamPolicyGrantPath } from "./grant-path.js";
+import type { IamPolicyStore } from "./store.js";
+/** The reads this controller makes of the identity-account port: the caller's account and display enrichment. */
+export type IamPolicyAccounts = AccountsByCaller & AccountsByIds;
+export interface IamPolicyControllerDeps {
+    readonly grantPath: IamPolicyGrantPath;
+    readonly policies: IamPolicyStore;
+    readonly accounts: IamPolicyAccounts;
+    /** The ONE composed Authorizer — position 1 of every chain and every direct handler's `authorizeDirect`. */
+    readonly authorizer: Authorizer;
+    /** The composed grant scope, or open source's organization-only default (compose.ts installs it at the `??` site). */
+    readonly grantScope: PolicyGrantScope;
+    /** The composed query engine — undefined = the tuple-half RPCs refuse UNIMPLEMENTED. */
+    readonly queries: AuthorizationQueryEngine | undefined;
+    /** The served edition — `checkMyPermission`'s first arm reads a kind's tier against it. */
+    readonly edition: ServerEdition;
+    readonly logger: Logger;
+}
+/** Registers both IamPolicy services on the router (routes stage). */
+export declare function registerIamPolicyServices(router: ConnectRouter, deps: IamPolicyControllerDeps): void;
+//# sourceMappingURL=controller.d.ts.map

package/dist/domain/iampolicy/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/domain/iampolicy/controller.ts"],"names":[],"mappings":"AAgGA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAqCzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uDAAuD,CAAC;AAE3F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAmB/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAStE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAe1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAcjD,iHAAiH;AACjH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEjE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,4GAA4G;IAC5G,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,sHAAsH;IACtH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,wBAAwB,GAAG,SAAS,CAAC;IACvD,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CA0CN"}