@plantops/contracts 0.1.0

package/dist/registry.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Registry contract — the platform-admin catalog surface (Doc 06 §4).
+ *
+ * Three tables, one vocabulary: `application` is what a module *is*,
+ * `permission` is what it can be granted, `nav_node` is what it shows. All three
+ * are **catalog**, not tenant data (Doc 07 §6): they carry no `client_id`, every
+ * authenticated subject can read them, and only a platform admin writes them.
+ *
+ * ## Natural keys, and why the DTOs carry both halves
+ *
+ * Every row here has two identifiers: a uuid, and a `key` that is unique within
+ * its parent (`application.key` globally, `permission.key` and `nav_node.key`
+ * per application). Both are returned, deliberately. The uuid is what a
+ * `role_permission` or `menu_permission` row references; the key is what a
+ * manifest is written against (Doc 02 §2) and what an operator recognises. A
+ * contract that returned only one of them would force every consumer to keep its
+ * own lookup table to get back the other.
+ *
+ * Field naming is snake_case, matching {@link ServiceAccountDTO} and the bodies
+ * Doc 06 §3 writes out — these are published shapes, and a convention that
+ * changes between two endpoints of the same API is worse than either
+ * convention.
+ */
+import type { NavNodeKind } from './nav.js';
+/**
+ * One registered application (Doc 01 §3.1).
+ *
+ * `is_active = false` is the global off switch of Doc 02 §7: the app is hidden
+ * everywhere and **all of its data is preserved**. There is no delete, because a
+ * deleted application would cascade away the permissions that existing role
+ * mappings and audit rows still refer to.
+ */
+export interface ApplicationDTO {
+    id: string;
+    /** Machine key, e.g. `gatepass`. Globally unique and never editable. */
+    key: string;
+    name: string;
+    description: string | null;
+    is_active: boolean;
+    /** Free-form per-application settings (Doc 01 §3.1). */
+    config: Record<string, unknown>;
+    /** ISO-8601. */
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * One atomic permission (Doc 01 §3.2).
+ *
+ * The key is the dotted `app.resource.action` form Doc 02 §2 writes; the pair
+ * `(application_id, key)` is unique, which is the 409 in Doc 06 §4.
+ */
+export interface PermissionDTO {
+    id: string;
+    application_id: string;
+    key: string;
+    name: string;
+    description: string | null;
+    is_active: boolean;
+    /** ISO-8601. */
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * One nav node as the **catalog** holds it (Doc 01 §3.3).
+ *
+ * Distinct from {@link NavNodeDTO}, which is the *resolved* tree a subject sees
+ * (Doc 05 §4): that one is pruned to what the subject may see and therefore
+ * omits `is_active`, `is_public` and `requires`, because a pruned tree has
+ * already answered the question those fields exist to decide. This one is the
+ * platform admin's view of what exists, visible or not.
+ */
+export interface NavNodeCatalogDTO {
+    id: string;
+    application_id: string;
+    /** `null` = top level. A parent always belongs to the same application. */
+    parent_id: string | null;
+    kind: NavNodeKind;
+    /** Unique within the application; the manifest upsert's natural key. */
+    key: string;
+    label: string;
+    route: string | null;
+    /** Icon *key* — the frontend maps it to its own icon set (Doc 05 §7). */
+    icon: string | null;
+    sort_order: number;
+    is_active: boolean;
+    /** Leaf-only opt-in: an unmapped leaf is visible anyway (Doc 05 §3). */
+    is_public: boolean;
+    /**
+     * Keys of the permissions mapped to this node, OR semantics (Doc 01 §4.4).
+     *
+     * Included so the tree is inspectable in one call: the mapping is the whole
+     * point of a nav node, and a catalog view that omits it sends every caller
+     * back for a second request to find out whether a node is reachable at all.
+     */
+    requires: string[];
+    /** ISO-8601. */
+    created_at: string;
+    updated_at: string;
+    children: NavNodeCatalogDTO[];
+}
+/** `GET /iam/applications/:id/nav` — the application's full catalog tree. */
+export interface NavCatalogResponse {
+    application_id: string;
+    /** Top-level nodes, each with its descendants, ordered by `sort_order`. */
+    tree: NavNodeCatalogDTO[];
+}
+/** `POST /iam/applications` body (Doc 06 §4). */
+export interface CreateApplicationRequest {
+    key: string;
+    name: string;
+    description?: string;
+    config?: Record<string, unknown>;
+}
+/**
+ * `PATCH /iam/applications/:id` body (Doc 06 §4) — update, or activate /
+ * deactivate.
+ *
+ * `key` is absent on purpose: it is the natural key every manifest upload and
+ * every permission address is written against (Doc 02 §2), so renaming it would
+ * silently re-point an entire catalog.
+ */
+export interface UpdateApplicationRequest {
+    name?: string;
+    description?: string | null;
+    is_active?: boolean;
+    config?: Record<string, unknown>;
+}
+/** One entry of the `POST /iam/applications/:id/permissions` body. */
+export interface CreatePermissionInput {
+    key: string;
+    name: string;
+    description?: string;
+}
+/** `POST /iam/applications/:id/permissions` body — bulk (Doc 02 §2 step 2). */
+export interface CreatePermissionsRequest {
+    permissions: CreatePermissionInput[];
+}
+/**
+ * One entry of the `POST /iam/applications/:id/nav` body.
+ *
+ * The parent is named by **either** `parent_id` or `parent_key`, never both.
+ * `parent_key` may name a node created earlier in the same request, which is
+ * what lets one call build a module and its menus in the order Doc 02 §2 step 3
+ * describes.
+ */
+export interface CreateNavNodeInput {
+    kind: NavNodeKind;
+    key: string;
+    label: string;
+    route?: string;
+    icon?: string;
+    sort_order?: number;
+    is_public?: boolean;
+    parent_id?: string;
+    parent_key?: string;
+}
+/** `POST /iam/applications/:id/nav` body — bulk (Doc 02 §2 step 3). */
+export interface CreateNavNodesRequest {
+    nodes: CreateNavNodeInput[];
+}
+/** One nav node and the permission keys being mapped to (or unmapped from) it. */
+export interface NavPermissionMapping {
+    nav_key: string;
+    permission_keys: string[];
+}
+/**
+ * `POST` / `DELETE /iam/applications/:id/nav-permissions` body (Doc 02 §2 step 4).
+ *
+ * Both directions take the same shape because they are the same statement in
+ * opposite directions, and both are idempotent: mapping what is already mapped
+ * and unmapping what is not are no-ops that audit nothing.
+ */
+export interface NavPermissionsRequest {
+    mappings: NavPermissionMapping[];
+}
+/** What a mapping call changed — the counts, plus the pairs it touched. */
+export interface NavPermissionsResult {
+    /** Rows actually inserted (`POST`) or deleted (`DELETE`). */
+    changed: number;
+    /** Pairs already in the requested state, which changed nothing. */
+    unchanged: number;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,IAAI,EAAE,iBAAiB,EAAE,CAAC;CAC3B;AAED,iDAAiD;AACjD,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,qBAAqB,EAAE,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/registry.js

@@ -0,0 +1,24 @@
+/**
+ * Registry contract — the platform-admin catalog surface (Doc 06 §4).
+ *
+ * Three tables, one vocabulary: `application` is what a module *is*,
+ * `permission` is what it can be granted, `nav_node` is what it shows. All three
+ * are **catalog**, not tenant data (Doc 07 §6): they carry no `client_id`, every
+ * authenticated subject can read them, and only a platform admin writes them.
+ *
+ * ## Natural keys, and why the DTOs carry both halves
+ *
+ * Every row here has two identifiers: a uuid, and a `key` that is unique within
+ * its parent (`application.key` globally, `permission.key` and `nav_node.key`
+ * per application). Both are returned, deliberately. The uuid is what a
+ * `role_permission` or `menu_permission` row references; the key is what a
+ * manifest is written against (Doc 02 §2) and what an operator recognises. A
+ * contract that returned only one of them would force every consumer to keep its
+ * own lookup table to get back the other.
+ *
+ * Field naming is snake_case, matching {@link ServiceAccountDTO} and the bodies
+ * Doc 06 §3 writes out — these are published shapes, and a convention that
+ * changes between two endpoints of the same API is worse than either
+ * convention.
+ */
+export {};

package/dist/roles.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Role contract — the WHAT of the access equation (Doc 01 §4.2, Doc 06 §7).
+ *
+ * A role is a tenant-defined **bundle of catalog permissions**. It is the only
+ * one of the three dimensions a client composes for itself: the permissions come
+ * from the platform's catalog (Doc 02 §2), the scope nodes come from the client's
+ * own org tree ({@link ScopeNodeDTO}), and a `role_binding` ties a subject to one
+ * of each (Doc 01 §4.5).
+ *
+ * ## Why a role carries no permissions inline
+ *
+ * {@link RoleDTO} reports how many permissions it maps, not which — the mapping
+ * is its own endpoint, `GET /iam/roles/:id/permissions`, returning
+ * {@link RolePermissionsResponse}. Two reasons, and the second is the real one:
+ *
+ * - a role list is a list of names and counts (Doc 09 §3.2), and inlining a
+ *   two-hundred-key permission set into every row of it is a payload nobody
+ *   reads; and
+ * - the mapping needs *more* than the permission — the owning application, and
+ *   whether that application is still enabled for the tenant — which the role
+ *   list has no business carrying.
+ *
+ * ## What "enabled" has to do with any of this
+ *
+ * Doc 02 §6: a role may only map permissions belonging to applications **enabled
+ * for that role's client**. That is a rule about the moment a mapping is
+ * *created*. It is deliberately not a rule about the moment one is *read*,
+ * because Doc 02 §7 preserves mappings when an application is disabled — they go
+ * inert, not away, so that re-enabling is a toggle rather than a re-setup. So
+ * {@link RolePermissionDTO} publishes `application_enabled`: a mapped permission
+ * that grants nothing today is a thing an operator has to be able to see, and a
+ * response that silently omitted it would make a disabled application look like
+ * a role someone had quietly edited.
+ *
+ * Field naming is snake_case, matching every other published shape here.
+ */
+/**
+ * How many permissions one `PUT /iam/roles/:id/permissions` may set.
+ *
+ * The same bound the catalog's own bulk seed uses, and for the same reason: the
+ * whole array is validated and written inside one request transaction, so an
+ * unbounded body is an unbounded transaction. A role that needs more than two
+ * hundred atomic permissions is a role that wants splitting.
+ */
+export declare const MAX_PERMISSIONS_PER_ROLE = 200;
+/**
+ * One tenant-defined role (Doc 01 §4.2).
+ *
+ * `is_system` marks a role the tenant did not create and may not rename or
+ * delete — today that is the `Client Admin` role seeded with the tenant's first
+ * administrator (Doc 02 §3 step 3). Its *permissions* are still set through the
+ * ordinary endpoint, because a system role with no way to be given permissions
+ * would be a role that can never do anything.
+ *
+ * The two counts are Doc 09 §3.2's list columns, which is the whole reason they
+ * are on the DTO rather than left to the caller to assemble.
+ */
+export interface RoleDTO {
+    id: string;
+    client_id: string;
+    /** Unique within the client — `unique (client_id, name)` (migration 0003). */
+    name: string;
+    description: string | null;
+    /** Seeded by the platform; not renamable and not deletable by the tenant. */
+    is_system: boolean;
+    /** Rows in `role_permission`, enabled or not. Doc 09 §3.2's "# permissions". */
+    permission_count: number;
+    /**
+     * Distinct subjects bound to this role anywhere in the tree — Doc 09 §3.2's
+     * "# users bound".
+     *
+     * Distinct *subjects*, not bindings: one user bound at three plants is one
+     * person with access, which is what the column is read as. It counts service
+     * accounts too, since a machine identity holding a role is exactly as much a
+     * consequence of deleting it (Doc 01 §4.5).
+     */
+    bound_subject_count: number;
+    /** ISO-8601. */
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * One permission as a role maps it (Doc 01 §4.3).
+ *
+ * A {@link PermissionDTO} widened with the two facts that decide whether the
+ * mapping currently grants anything: which application it belongs to, and
+ * whether that application is still enabled for this tenant. Both are joined in
+ * rather than left for the caller to fetch, because the permission picker of
+ * Doc 09 §3.2 groups by application and cannot render a row without them.
+ */
+export interface RolePermissionDTO {
+    id: string;
+    key: string;
+    name: string;
+    description: string | null;
+    /** The catalog's own switch — `false` once a manifest retires the key (Doc 02 §7). */
+    is_active: boolean;
+    application_id: string;
+    application_key: string;
+    application_name: string;
+    /**
+     * Whether the owning application is enabled for this role's client.
+     *
+     * `false` means the mapping is **inert but preserved** (Doc 02 §7): it grants
+     * nothing today and grants again the moment the application is re-enabled.
+     * A new mapping cannot be created in this state — that is the Doc 02 §6 rule —
+     * but an existing one is never silently dropped.
+     */
+    application_enabled: boolean;
+}
+/**
+ * `GET` / `PUT /iam/roles/:id/permissions` → the role's whole mapping
+ * (Doc 06 §7).
+ *
+ * Not paginated, for the reason `/iam/permissions/resolve` is not: this is one
+ * editable unit — a picker either shows the whole selection or shows a lie —
+ * and it is bounded by {@link MAX_PERMISSIONS_PER_ROLE} rather than by a page
+ * size. Ordered by application key, then permission key, so the grouping the UI
+ * renders is the order it arrives in.
+ */
+export interface RolePermissionsResponse {
+    role_id: string;
+    permissions: RolePermissionDTO[];
+}
+/**
+ * `GET /iam/roles/permission-catalog` → everything a role of this tenant may be
+ * given (Doc 06 §7, Doc 09 §3.2).
+ *
+ * ## Why this exists at all
+ *
+ * Doc 09 §3.2's permission picker offers "only apps enabled for the client", and
+ * until this endpoint there was no way for a tenant administrator to find out
+ * what those were: the catalog lives behind `iam.platform.permission.read`, which
+ * is platform authority no client admin holds, and
+ * `GET /iam/roles/:id/permissions` answers a narrower question — what one role
+ * already carries. A picker built from that could only ever offer what was
+ * already chosen.
+ *
+ * ## Every entry is one `PUT /iam/roles/:id/permissions` will accept
+ *
+ * The set is exactly the four conditions that endpoint validates (Doc 02 §6):
+ * the permission is active, its application is active in the registry, and that
+ * application is enabled for this client. Anything the picker offers is
+ * therefore mappable, which is what makes a 409 from a save a real conflict —
+ * something changed underneath — rather than the ordinary result of choosing a
+ * row that was on screen.
+ *
+ * ## It reuses {@link RolePermissionDTO}
+ *
+ * `is_active` and `application_enabled` are constant `true` for every entry
+ * here, by construction. They are on the wire anyway so that a picker can hold
+ * catalog entries and a role's own *inert* mappings — a preserved
+ * `role_permission` whose application is currently disabled (Doc 02 §7) — in one
+ * list without a union type. Those two are the rows that differ, and they are
+ * the rows the screen has to render differently.
+ */
+export interface PermissionCatalogResponse {
+    /** The caller's tenant, from the token — never from a query parameter. */
+    client_id: string;
+    /** Ordered by application name, then by permission key. */
+    permissions: RolePermissionDTO[];
+}
+/**
+ * `POST /iam/roles` body (Doc 06 §7).
+ *
+ * The client is the caller's own, taken from the token's `cid` and from nowhere
+ * else — there is no `client_id` field here and there will not be one, for the
+ * reason `/iam/scopes` has no `?clientId=`: it would look like it selected a
+ * tenant while RLS quietly ignored it.
+ *
+ * `is_system` is likewise absent. A tenant that could set it would be able to
+ * make a role it cannot afterwards delete.
+ */
+export interface CreateRoleRequest {
+    name: string;
+    description?: string;
+}
+/**
+ * `PATCH /iam/roles/:id` body — Doc 06 §7's "rename", plus the description.
+ *
+ * The description rides along because it is the same row's editable prose and
+ * Doc 10 §4 gives roles a `role.updated` action to record it under — the test
+ * `updateScopeNodeSchema` fails, which is why the scope tree's PATCH is narrower
+ * than this one rather than the other way round.
+ *
+ * Permissions are **not** here. They are a `PUT` of their own, because setting
+ * them is a replacement of a set with cross-tenant validation attached
+ * (Doc 02 §6), not a field of the role.
+ */
+export interface UpdateRoleRequest {
+    name?: string;
+    description?: string;
+}
+/**
+ * `PUT /iam/roles/:id/permissions` body (Doc 06 §7).
+ *
+ * A `PUT` of the whole set, not a pair of add/remove calls: "which permissions
+ * does this role have" is one question with one answer, and an editor that saves
+ * a picker's state has exactly one set to send. An empty array is legal and
+ * means what it says — the role maps nothing.
+ *
+ * ## Ids, not keys
+ *
+ * A permission `key` is unique only within its application (`unique
+ * (application_id, key)`), so a bare key names a permission only if you already
+ * know which application is meant. Accepting keys would therefore mean accepting
+ * pairs, and a role editor gets its ids from
+ * `GET /iam/applications/:id/permissions` — the same call that renders the
+ * picker — so the pair would be assembled from data the caller already holds and
+ * then taken apart again on arrival.
+ */
+export interface SetRolePermissionsRequest {
+    permission_ids: string[];
+}
+//# sourceMappingURL=roles.d.ts.map

package/dist/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sFAAsF;IACtF,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,iBAAiB,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,WAAW,EAAE,iBAAiB,EAAE,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B"}

package/dist/roles.js

@@ -0,0 +1,45 @@
+/**
+ * Role contract — the WHAT of the access equation (Doc 01 §4.2, Doc 06 §7).
+ *
+ * A role is a tenant-defined **bundle of catalog permissions**. It is the only
+ * one of the three dimensions a client composes for itself: the permissions come
+ * from the platform's catalog (Doc 02 §2), the scope nodes come from the client's
+ * own org tree ({@link ScopeNodeDTO}), and a `role_binding` ties a subject to one
+ * of each (Doc 01 §4.5).
+ *
+ * ## Why a role carries no permissions inline
+ *
+ * {@link RoleDTO} reports how many permissions it maps, not which — the mapping
+ * is its own endpoint, `GET /iam/roles/:id/permissions`, returning
+ * {@link RolePermissionsResponse}. Two reasons, and the second is the real one:
+ *
+ * - a role list is a list of names and counts (Doc 09 §3.2), and inlining a
+ *   two-hundred-key permission set into every row of it is a payload nobody
+ *   reads; and
+ * - the mapping needs *more* than the permission — the owning application, and
+ *   whether that application is still enabled for the tenant — which the role
+ *   list has no business carrying.
+ *
+ * ## What "enabled" has to do with any of this
+ *
+ * Doc 02 §6: a role may only map permissions belonging to applications **enabled
+ * for that role's client**. That is a rule about the moment a mapping is
+ * *created*. It is deliberately not a rule about the moment one is *read*,
+ * because Doc 02 §7 preserves mappings when an application is disabled — they go
+ * inert, not away, so that re-enabling is a toggle rather than a re-setup. So
+ * {@link RolePermissionDTO} publishes `application_enabled`: a mapped permission
+ * that grants nothing today is a thing an operator has to be able to see, and a
+ * response that silently omitted it would make a disabled application look like
+ * a role someone had quietly edited.
+ *
+ * Field naming is snake_case, matching every other published shape here.
+ */
+/**
+ * How many permissions one `PUT /iam/roles/:id/permissions` may set.
+ *
+ * The same bound the catalog's own bulk seed uses, and for the same reason: the
+ * whole array is validated and written inside one request transaction, so an
+ * unbounded body is an unbounded transaction. A role that needs more than two
+ * hundred atomic permissions is a role that wants splitting.
+ */
+export const MAX_PERMISSIONS_PER_ROLE = 200;