@plantops/contracts 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# contracts
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build contracts` to build the library.
+
+## Running unit tests
+
+Run `nx test contracts` to execute the unit tests via [Jest](https://jestjs.io).

package/dist/audit.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The audit read surface — `GET /iam/audit` and its CSV export
+ * (Doc 06 §12, Doc 10 §2, §7).
+ *
+ * The trail is written from a dozen places and read from exactly one, and this
+ * file describes the reading half. Everything about the writing half — the
+ * action catalog, the redaction boundary, the `SECURITY DEFINER` writer — is
+ * deliberately absent: a consumer of this contract cannot write an audit row and
+ * must not be given a type that suggests otherwise (Doc 10 §7: "audit is
+ * read-only through the API — there is no mutate/delete endpoint by design").
+ *
+ * ## Why `action` and `target_type` are plain strings here
+ *
+ * The IAM types both narrowly for its *writers* — `AUDIT_ACTIONS` and
+ * `AUDIT_TARGET_TYPES` in `apps/iam-api/src/audit/audit-actions.ts` — so a
+ * misspelling does not compile. A *reader* cannot be typed that way, and the
+ * reason is the whole point of an append-only table: rows outlive the catalog
+ * that wrote them. An action retired in a later version, or a `target_type`
+ * naming a table since renamed, is still in the trail and must still be
+ * readable; a union here would make the compiler refuse to describe history that
+ * the database is contractually obliged to keep (Doc 10 §1, §6).
+ *
+ * `actor_type` is the exception, and it is the exception for the opposite
+ * reason: it is a Postgres enum (migration 0001) rather than a convention, so
+ * the database itself guarantees the three values — see {@link AuditActorType}.
+ */
+import type { PaginationQuery } from './pagination.js';
+/**
+ * Who took the action (Doc 10 §2).
+ *
+ * Derived inside `iam.write_audit` from the session context rather than passed
+ * by any caller, which is what makes it non-forgeable (migration 0010): a
+ * platform context stamps `platform`, an authenticated user `user`, and anything
+ * else `service_account`.
+ *
+ * Spelled here rather than imported from `@plantops/db`, which contracts must
+ * not depend on — it has zero dependencies by design (Doc 08 §3). The Postgres
+ * enum is the same three values in the same order, and `libs/db`'s
+ * `entities.spec.ts` asserts the two spellings against each other so they cannot
+ * drift into an `actor_type` the API publishes and the column never produces.
+ * Same arrangement as `UserStatus` and `ClientStatus`.
+ */
+export declare const AuditActorType: {
+    readonly USER: "user";
+    readonly SERVICE_ACCOUNT: "service_account";
+    readonly PLATFORM: "platform";
+};
+export type AuditActorType = (typeof AuditActorType)[keyof typeof AuditActorType];
+export declare const AUDIT_ACTOR_TYPE_VALUES: readonly ["user", "service_account", "platform"];
+/**
+ * One record of the trail, exactly as Doc 10 §2 shapes it (Doc 01 §4.8).
+ *
+ * Every nullable field is nullable for a stated reason, and none of them is an
+ * oversight:
+ *
+ * - **`client_id`** — null means a platform-level action, outside any tenant.
+ *   Only a platform admin ever sees such a row (Doc 10 §7).
+ * - **`actor_id`** — null where there was no subject to name. `platform.bootstrap`
+ *   runs before any subject exists (migration 0011), and a failed login names an
+ *   account that may not have matched anything.
+ * - **`target_type` / `target_id`** — null where the event has no row to point
+ *   at: a bulk upload reports counts, a denied request names a permission. The
+ *   table's `audit_trail_target_is_typed` check means an id never arrives
+ *   without a type, so the two are null together or the type alone is set.
+ *
+ * `payload` is whatever context the writer attached, after passing the redaction
+ * boundary of Doc 10 §8 — so a consumer may render it, but must not assume any
+ * particular key: the shape varies by action, and secrets are structurally
+ * absent rather than merely omitted.
+ */
+export interface AuditRecordDTO {
+    id: string;
+    /** Null ⇒ a platform-level action, outside any tenant (Doc 10 §2). */
+    client_id: string | null;
+    actor_type: AuditActorType;
+    /** Null where the event had no subject to attribute. */
+    actor_id: string | null;
+    /** A dotted verb from the Doc 10 §4 catalog — see the header on typing. */
+    action: string;
+    /** The table the target lives in, or null where the event names no row. */
+    target_type: string | null;
+    target_id: string | null;
+    /** Redacted context (Doc 10 §8). Shape varies by action. */
+    payload: Record<string, unknown>;
+    /** ISO-8601. */
+    created_at: string;
+}
+/**
+ * The filters of Doc 06 §12, composable in any combination (Doc 10 §1.4:
+ * "filterable by actor, action, target, client, and time").
+ *
+ * Every one of them **narrows** and none of them widens. That is the property
+ * that makes the same query object safe for both tiers: visibility is decided by
+ * the `audit_trail_read` RLS policy from the caller's own context (migration
+ * 0010), so a client admin passing `client_id` of another tenant gets an empty
+ * page rather than a refusal — the same answer they would get for a client that
+ * does not exist, which is what Doc 06 §2 requires of anything that could
+ * otherwise become a cross-tenant existence oracle.
+ *
+ * `from` and `to` are ISO-8601 instants compared against `created_at`, `from`
+ * inclusive and `to` exclusive — the half-open convention that lets a caller
+ * page a month by asking for `[2026-08-01, 2026-09-01)` without owning the
+ * boundary problem.
+ */
+export interface AuditQuery extends PaginationQuery {
+    /** The subject who acted — `actor_id`. */
+    actor_id?: string;
+    actor_type?: AuditActorType;
+    /** An exact action from the Doc 10 §4 catalog. */
+    action?: string;
+    target_type?: string;
+    target_id?: string;
+    /** The tenant whose rows to show; only ever narrows what RLS already allows. */
+    client_id?: string;
+    /** Inclusive lower bound on `created_at`, ISO-8601. */
+    from?: string;
+    /** Exclusive upper bound on `created_at`, ISO-8601. */
+    to?: string;
+}
+/** {@link AuditQuery} without the page — an export is of the whole filter. */
+export type AuditExportQuery = Omit<AuditQuery, 'page' | 'limit'>;
+/**
+ * The most rows one CSV export may carry.
+ *
+ * A ceiling rather than a page, because an export is a document: a compliance
+ * reader who asked for a quarter and silently received its first ten thousand
+ * events has a file that *looks* complete and is not, which is a worse failure
+ * than no file at all. So a filter matching more than this is refused with the
+ * count and a suggestion to narrow the range (Doc 06 §2's `VALIDATION_FAILED`),
+ * and every export that succeeds is the complete answer to what was asked.
+ *
+ * Ten thousand rows of this shape is a few megabytes — comfortably inside what a
+ * spreadsheet opens and what a response can be assembled in.
+ */
+export declare const AUDIT_EXPORT_MAX_ROWS = 10000;
+/**
+ * The CSV column order, which is part of the contract.
+ *
+ * An export is consumed by spreadsheets and by scripts, and both break when
+ * columns move. Publishing the order here rather than leaving it inside the
+ * server means a consumer can assert on it, and means the header row and the
+ * value row cannot disagree — `audit-csv.ts` builds both from this list.
+ */
+export declare const AUDIT_EXPORT_COLUMNS: readonly ["id", "created_at", "client_id", "actor_type", "actor_id", "action", "target_type", "target_id", "payload"];
+export type AuditExportColumn = (typeof AUDIT_EXPORT_COLUMNS)[number];
+/** `Content-Type` of the export, and what the browser saves it as. */
+export declare const AUDIT_EXPORT_CONTENT_TYPE = "text/csv; charset=utf-8";
+export declare const AUDIT_EXPORT_FILENAME = "audit-export.csv";
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAElF,eAAO,MAAM,uBAAuB,kDAIU,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,cAAc,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,uHAUqB,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AACnE,eAAO,MAAM,qBAAqB,qBAAqB,CAAC"}

package/dist/audit.js

@@ -0,0 +1,87 @@
+/**
+ * The audit read surface — `GET /iam/audit` and its CSV export
+ * (Doc 06 §12, Doc 10 §2, §7).
+ *
+ * The trail is written from a dozen places and read from exactly one, and this
+ * file describes the reading half. Everything about the writing half — the
+ * action catalog, the redaction boundary, the `SECURITY DEFINER` writer — is
+ * deliberately absent: a consumer of this contract cannot write an audit row and
+ * must not be given a type that suggests otherwise (Doc 10 §7: "audit is
+ * read-only through the API — there is no mutate/delete endpoint by design").
+ *
+ * ## Why `action` and `target_type` are plain strings here
+ *
+ * The IAM types both narrowly for its *writers* — `AUDIT_ACTIONS` and
+ * `AUDIT_TARGET_TYPES` in `apps/iam-api/src/audit/audit-actions.ts` — so a
+ * misspelling does not compile. A *reader* cannot be typed that way, and the
+ * reason is the whole point of an append-only table: rows outlive the catalog
+ * that wrote them. An action retired in a later version, or a `target_type`
+ * naming a table since renamed, is still in the trail and must still be
+ * readable; a union here would make the compiler refuse to describe history that
+ * the database is contractually obliged to keep (Doc 10 §1, §6).
+ *
+ * `actor_type` is the exception, and it is the exception for the opposite
+ * reason: it is a Postgres enum (migration 0001) rather than a convention, so
+ * the database itself guarantees the three values — see {@link AuditActorType}.
+ */
+/**
+ * Who took the action (Doc 10 §2).
+ *
+ * Derived inside `iam.write_audit` from the session context rather than passed
+ * by any caller, which is what makes it non-forgeable (migration 0010): a
+ * platform context stamps `platform`, an authenticated user `user`, and anything
+ * else `service_account`.
+ *
+ * Spelled here rather than imported from `@plantops/db`, which contracts must
+ * not depend on — it has zero dependencies by design (Doc 08 §3). The Postgres
+ * enum is the same three values in the same order, and `libs/db`'s
+ * `entities.spec.ts` asserts the two spellings against each other so they cannot
+ * drift into an `actor_type` the API publishes and the column never produces.
+ * Same arrangement as `UserStatus` and `ClientStatus`.
+ */
+export const AuditActorType = {
+    USER: 'user',
+    SERVICE_ACCOUNT: 'service_account',
+    PLATFORM: 'platform',
+};
+export const AUDIT_ACTOR_TYPE_VALUES = [
+    AuditActorType.USER,
+    AuditActorType.SERVICE_ACCOUNT,
+    AuditActorType.PLATFORM,
+];
+/**
+ * The most rows one CSV export may carry.
+ *
+ * A ceiling rather than a page, because an export is a document: a compliance
+ * reader who asked for a quarter and silently received its first ten thousand
+ * events has a file that *looks* complete and is not, which is a worse failure
+ * than no file at all. So a filter matching more than this is refused with the
+ * count and a suggestion to narrow the range (Doc 06 §2's `VALIDATION_FAILED`),
+ * and every export that succeeds is the complete answer to what was asked.
+ *
+ * Ten thousand rows of this shape is a few megabytes — comfortably inside what a
+ * spreadsheet opens and what a response can be assembled in.
+ */
+export const AUDIT_EXPORT_MAX_ROWS = 10_000;
+/**
+ * The CSV column order, which is part of the contract.
+ *
+ * An export is consumed by spreadsheets and by scripts, and both break when
+ * columns move. Publishing the order here rather than leaving it inside the
+ * server means a consumer can assert on it, and means the header row and the
+ * value row cannot disagree — `audit-csv.ts` builds both from this list.
+ */
+export const AUDIT_EXPORT_COLUMNS = [
+    'id',
+    'created_at',
+    'client_id',
+    'actor_type',
+    'actor_id',
+    'action',
+    'target_type',
+    'target_id',
+    'payload',
+];
+/** `Content-Type` of the export, and what the browser saves it as. */
+export const AUDIT_EXPORT_CONTENT_TYPE = 'text/csv; charset=utf-8';
+export const AUDIT_EXPORT_FILENAME = 'audit-export.csv';

package/dist/bindings.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Role-binding contract — WHO × WHAT × WHERE in one row (Doc 01 §4.5,
+ * Doc 06 §9, Doc 09 §3.4).
+ *
+ * The other three client-tier contracts each describe one dimension: a
+ * {@link UserDTO} or a {@link ServiceAccountDTO} is a WHO, a {@link RoleDTO} is
+ * a bundle of WHATs, a {@link ScopeNodeDTO} is a WHERE. None of them grants
+ * anything. A binding is the only shape in the system that does, and everything
+ * below follows from that.
+ *
+ * ## One subject, expressed as one pair
+ *
+ * The table carries two nullable subject columns with a check constraint making
+ * exactly one of them set (Doc 01 §4.5, migration 0004). That is the right shape
+ * for a schema — a subject is genuinely a user *or* a service account, with a
+ * foreign key each — and the wrong shape for a response: a consumer that had to
+ * test which of two fields was populated would be re-deriving, in every client,
+ * what the constraint already guarantees. So {@link RoleBindingDTO} publishes
+ * {@link RoleBindingDTO.subject_type} and {@link RoleBindingDTO.subject_id},
+ * which is the same collapse the duplicate-prevention index makes with its
+ * `coalesce(user_id, service_account_id)`.
+ *
+ * {@link CreateRoleBindingRequest} goes the other way and keeps the two columns
+ * apart, because a request is where the XOR is *decided* rather than reported —
+ * a `subject_type` discriminator there would let a caller name a user id and
+ * label it a service account, and the resulting 409 would be about the wrong
+ * thing.
+ *
+ * ## Expiry does not remove a binding from this surface
+ *
+ * `expires_at` is enforced at resolve time (Doc 04 §4.1) and nowhere else: a
+ * lapsed grant stops granting and stays a row. So expired bindings are listed
+ * and flagged rather than filtered, for the reason {@link UserBindingDTO.expired}
+ * gives — "why did this stop working last Friday" is a question only the row can
+ * answer — and because Doc 01 §4.5 makes time passing a thing that fires no
+ * event at all.
+ *
+ * Field naming is snake_case, matching every other published shape here.
+ */
+import type { SubjectType } from './jwt.js';
+import type { PaginationQuery } from './pagination.js';
+/**
+ * One grant (Doc 01 §4.5).
+ *
+ * The names beside every id — `role_name`, `scope_node_name`, `subject_name` —
+ * are joined in rather than left to the caller, for the reason
+ * {@link UserBindingDTO} gives: a binding rendered as four uuids is not a
+ * rendering of anything, and Doc 09 §3.4's list is the screen an operator
+ * reviews access on.
+ */
+export interface RoleBindingDTO {
+    /** The row `DELETE /iam/role-bindings/:id` takes. */
+    id: string;
+    client_id: string;
+    /** Which of the two subject columns is set — see the header. */
+    subject_type: SubjectType;
+    /** The `user` or `service_account` id, whichever {@link subject_type} names. */
+    subject_id: string;
+    /** `user.full_name` or `service_account.name`. */
+    subject_name: string;
+    /** The user's address; `null` for a service account, which has none. */
+    subject_email: string | null;
+    role_id: string;
+    role_name: string;
+    scope_node_id: string;
+    scope_node_name: string;
+    /** The materialized `ltree` path — `n_<hex>` labels, never display names (Doc 01 §3.5). */
+    scope_node_path: string;
+    /** ISO-8601, or `null` for a grant that does not expire. */
+    expires_at: string | null;
+    /** Whether {@link expires_at} has passed — see the header. */
+    expired: boolean;
+    created_at: string;
+}
+/**
+ * `POST /iam/role-bindings` body (Doc 06 §9, Doc 09 §3.4).
+ *
+ * Doc 09 §3.4's single action: pick a subject, pick a role, pick a scope node,
+ * optionally set an expiry.
+ *
+ * `client_id` is absent, like everywhere else on the client tier: the tenant is
+ * the token's `cid`, and every one of the three ids is checked against it before
+ * a row is written (Doc 02 §6). Naming a role, node or subject from another
+ * client is a `409`, indistinguishable from naming one that does not exist —
+ * a binding request must not become a way to enumerate another tenant.
+ *
+ * Exactly one of {@link user_id} / {@link service_account_id}. Neither and both
+ * are `400`s: the body is malformed in a way no row could settle, so it is
+ * refused by the schema rather than by the check constraint.
+ *
+ * `expires_at` is ISO-8601 and must be in the future. A grant that lapsed before
+ * it was written grants nothing from the instant it exists, which is never what
+ * the operator meant.
+ */
+export interface CreateRoleBindingRequest {
+    user_id?: string;
+    service_account_id?: string;
+    role_id: string;
+    scope_node_id: string;
+    /** ISO-8601, in the future. Omit for a grant that does not expire. */
+    expires_at?: string;
+}
+/**
+ * `GET /iam/role-bindings` query (Doc 06 §9, Doc 09 §3.4).
+ *
+ * Doc 06 §9's "filter by user, role, scope", with the subject split into its two
+ * columns for the reason {@link CreateRoleBindingRequest} splits them.
+ *
+ * `scope_node_id` matches the node the binding is **anchored to**, not the
+ * subtree it covers. The two are different questions — "what was granted here"
+ * against "who can act here" — and only the first is a list of bindings; the
+ * second is `POST /iam/permissions/check` (Doc 06 §11), which answers it for a
+ * subject rather than by enumerating rows.
+ *
+ * Every filter is combined with `and`, so an unfiltered call is the tenant's
+ * whole grant table and a fully filtered one is the duplicate check an operator
+ * can run before binding.
+ */
+export interface RoleBindingsQuery extends PaginationQuery {
+    user_id?: string;
+    service_account_id?: string;
+    role_id?: string;
+    scope_node_id?: string;
+}
+//# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,YAAY,EAAE,WAAW,CAAC;IAC1B,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,eAAe,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/bindings.js

@@ -0,0 +1,40 @@
+/**
+ * Role-binding contract — WHO × WHAT × WHERE in one row (Doc 01 §4.5,
+ * Doc 06 §9, Doc 09 §3.4).
+ *
+ * The other three client-tier contracts each describe one dimension: a
+ * {@link UserDTO} or a {@link ServiceAccountDTO} is a WHO, a {@link RoleDTO} is
+ * a bundle of WHATs, a {@link ScopeNodeDTO} is a WHERE. None of them grants
+ * anything. A binding is the only shape in the system that does, and everything
+ * below follows from that.
+ *
+ * ## One subject, expressed as one pair
+ *
+ * The table carries two nullable subject columns with a check constraint making
+ * exactly one of them set (Doc 01 §4.5, migration 0004). That is the right shape
+ * for a schema — a subject is genuinely a user *or* a service account, with a
+ * foreign key each — and the wrong shape for a response: a consumer that had to
+ * test which of two fields was populated would be re-deriving, in every client,
+ * what the constraint already guarantees. So {@link RoleBindingDTO} publishes
+ * {@link RoleBindingDTO.subject_type} and {@link RoleBindingDTO.subject_id},
+ * which is the same collapse the duplicate-prevention index makes with its
+ * `coalesce(user_id, service_account_id)`.
+ *
+ * {@link CreateRoleBindingRequest} goes the other way and keeps the two columns
+ * apart, because a request is where the XOR is *decided* rather than reported —
+ * a `subject_type` discriminator there would let a caller name a user id and
+ * label it a service account, and the resulting 409 would be about the wrong
+ * thing.
+ *
+ * ## Expiry does not remove a binding from this surface
+ *
+ * `expires_at` is enforced at resolve time (Doc 04 §4.1) and nowhere else: a
+ * lapsed grant stops granting and stays a row. So expired bindings are listed
+ * and flagged rather than filtered, for the reason {@link UserBindingDTO.expired}
+ * gives — "why did this stop working last Friday" is a question only the row can
+ * answer — and because Doc 01 §4.5 makes time passing a thing that fires no
+ * event at all.
+ *
+ * Field naming is snake_case, matching every other published shape here.
+ */
+export {};

package/dist/clients.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Client contract — the tenant-provisioning surface (Doc 06 §5, Doc 02 §3).
+ *
+ * Three things live here, and they are three because provisioning a tenant is
+ * three separable decisions: **who the tenant is** ({@link ClientDTO}), **what
+ * they are allowed to run** ({@link ClientApplicationDTO}), and **who
+ * administers them on day one** ({@link ClientAdminDTO}). Doc 02 §3 lists them
+ * in that order and the API follows it, because each step is only meaningful
+ * once the one before it has happened.
+ *
+ * ## These are tenant rows described by a platform API
+ *
+ * Unlike {@link ApplicationDTO} and friends, everything here carries a
+ * `client_id` and lives behind RLS (Doc 07 §6). The surface is nonetheless
+ * platform-tier: a tenant does not create itself, and the endpoints are gated on
+ * `iam.platform.*`. That split is why the DTOs name the client explicitly rather
+ * than leaving it implied by the caller's token, the way the client-admin
+ * surfaces of Doc 06 §6–9 do.
+ *
+ * Field naming is snake_case, matching every other published shape in this
+ * package.
+ */
+/**
+ * A tenant's lifecycle states (Doc 01 §3.4).
+ *
+ * Two, and neither is `deleted`: a tenant is suspended, never removed. Doc 06 §5
+ * makes suspension the off switch — a suspended client's users cannot log in,
+ * which migration 0012's `auth_begin_session` enforces by re-checking
+ * `client.status` at the moment a session is created — while every scope node,
+ * role, binding and audit row it owns stays exactly where it was. Deleting a
+ * client would take an organisation's entire access history with it, and
+ * `on delete restrict` on every child table (migration 0003) makes sure nobody
+ * does it by accident.
+ *
+ * Spelled here rather than imported from `@plantops/db`, which contracts must
+ * not depend on — it has zero dependencies by design (Doc 08 §3). The Postgres
+ * enum is the same two values, and `libs/db`'s `entities.spec.ts` asserts the
+ * two spellings against each other so they cannot drift into a status the API
+ * accepts and the column rejects. Same arrangement as
+ * {@link ServiceAccountStatus}.
+ */
+export declare const ClientStatus: {
+    readonly ACTIVE: "active";
+    readonly SUSPENDED: "suspended";
+};
+export type ClientStatus = (typeof ClientStatus)[keyof typeof ClientStatus];
+export declare const CLIENT_STATUS_VALUES: readonly ["active", "suspended"];
+/**
+ * One tenant (Doc 01 §3.4).
+ *
+ * `slug` is half of the login credential — `POST /auth/login` takes
+ * `{ email, password, client_slug }` (Doc 03 §3) — which is why it is returned
+ * on every read and why nothing can change it.
+ */
+export interface ClientDTO {
+    id: string;
+    name: string;
+    /** Lowercase kebab-case, and the half of the login credential a user types. */
+    slug: string;
+    status: ClientStatus;
+    /** Free-form per-tenant settings (Doc 01 §3.4). */
+    config: Record<string, unknown>;
+    /**
+     * How many applications this client currently has **enabled**.
+     *
+     * Included because Doc 09 §2.2's client list shows exactly this column, and a
+     * list view that had to issue one extra request per row to render it would be
+     * a list view nobody keeps. Disabled `client_application` rows are not counted
+     * — they are preserved, not active (Doc 02 §7).
+     */
+    enabled_application_count: number;
+    /**
+     * Entitlements (Doc 11 §10, migration 0020). `null` is unlimited — the
+     * reading every pre-licence deployment relies on — and `expires_at` is the
+     * subscription term whose passing blocks administrative writes while leaving
+     * authentication and resolution working.
+     */
+    expires_at: string | null;
+    max_users: number | null;
+    max_sites: number | null;
+    /** ISO-8601. */
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * One application enabled for one client (Doc 01 §4.1).
+ *
+ * The application's `key` and `name` ride along with the ids for the reason
+ * {@link NavNodeCatalogDTO} carries `requires`: the toggle list of Doc 09 §2.2
+ * is unreadable as a column of uuids, and a consumer that had to join the
+ * catalog itself would be keeping a second copy of it.
+ *
+ * `enabled = false` is the tenant-level off switch of Doc 02 §7. The row stays,
+ * with its config, and every role mapping that referenced the app's permissions
+ * stays intact but inert — which is what makes re-enabling a toggle rather than
+ * a re-setup.
+ */
+export interface ClientApplicationDTO {
+    client_id: string;
+    application_id: string;
+    /** The application's machine key, e.g. `gatepass`. */
+    application_key: string;
+    application_name: string;
+    enabled: boolean;
+    /** Per-client settings for this application (Doc 01 §4.1). */
+    config: Record<string, unknown>;
+    /**
+     * The per-module bundle entitlements (Doc 11 §10, migration 0020). `null`
+     * inherits the tenant-wide value from the client row.
+     */
+    expires_at: string | null;
+    max_users: number | null;
+    max_sites: number | null;
+    /** ISO-8601. */
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * What `POST /iam/clients/:id/admins` created (Doc 06 §5, Doc 09 §2.2).
+ *
+ * Flat, and deliberately not a `UserDTO`: this describes the **bootstrap**, not
+ * a user resource. One call creates four rows that are only useful together —
+ * the user, the client's root scope node, the system client-admin role, and the
+ * binding that ties them — and the caller's next question is "can this person
+ * log in and see their whole organisation", which the four ids answer. The user
+ * management surface, and the `UserDTO` it publishes, is Doc 06 §8 / Session 18.
+ *
+ * No credential appears here. The password is chosen by the caller and is never
+ * echoed, stored in the clear, or written to the audit payload (Doc 10 §8).
+ */
+export interface ClientAdminDTO {
+    client_id: string;
+    user_id: string;
+    email: string;
+    full_name: string;
+    /** The system role the user was bound to — `is_system`, per Doc 06 §5. */
+    role_id: string;
+    role_name: string;
+    /** The client's root scope node: everything the admin's grants cover. */
+    scope_node_id: string;
+    scope_node_name: string;
+    /** The root's ltree path — one `n_<hex>` label (Doc 01 §3.5). */
+    scope_node_path: string;
+    role_binding_id: string;
+    /** ISO-8601. */
+    created_at: string;
+}
+/** `POST /iam/clients` body (Doc 06 §5). */
+export interface CreateClientRequest {
+    name: string;
+    slug: string;
+    config?: Record<string, unknown>;
+}
+/**
+ * `PATCH /iam/clients/:id` body (Doc 06 §5) — update, or suspend / reactivate.
+ *
+ * `slug` is absent on purpose, for a sharper version of the reason
+ * {@link UpdateApplicationRequest} omits `key`: the slug is not merely a natural
+ * key, it is something every one of the tenant's users types to log in
+ * (Doc 03 §3). Renaming it would lock out an entire organisation at once, and
+ * nothing in the row would look wrong afterwards.
+ */
+export interface UpdateClientRequest {
+    name?: string;
+    status?: ClientStatus;
+    config?: Record<string, unknown>;
+}
+/**
+ * One entry of the `POST /iam/clients/:id/applications` body.
+ *
+ * The application is named by **either** `application_id` or `application_key`,
+ * never both — the same rule, for the same reason, as
+ * {@link CreateNavNodeInput}'s two ways of naming a parent. The key is what an
+ * operator recognises and what a manifest is written against; the uuid is what a
+ * UI already holds after listing the catalog.
+ */
+export interface EnableApplicationInput {
+    application_id?: string;
+    application_key?: string;
+    config?: Record<string, unknown>;
+}
+/** `POST /iam/clients/:id/applications` body — bulk (Doc 02 §3 step 2). */
+export interface EnableApplicationsRequest {
+    applications: EnableApplicationInput[];
+}
+/** `PATCH /iam/clients/:id/applications/:appId` body (Doc 06 §5). */
+export interface UpdateClientApplicationRequest {
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+}
+/**
+ * `PATCH /iam/clients/:id/scopes/:scopeId/billable-site` — the site meter
+ * (Doc 11 §10.1).
+ *
+ * Platform-tier, and permanently so. The meter deliberately does not count
+ * `scope_node.kind`, because kind is tenant-supplied text (ADR 0002) and a
+ * quantity the customer can rename away is not a quantity anyone can invoice.
+ */
+export interface BillableSiteRequest {
+    billable_site: boolean;
+}
+/**
+ * `PATCH /iam/clients/:id/billable-sites` — the same meter, many nodes.
+ *
+ * One call for provisioning a tenant with dozens of sites. **All-or-nothing**:
+ * a batch that would breach `max_sites` is refused entire, naming the ceiling
+ * and what the batch would reach, because a half-applied billing change is a
+ * state nobody can reconcile later.
+ *
+ * Ids that are not this tenant's are absent from the response rather than an
+ * error — the same non-answer the single-node route gives, so that neither
+ * becomes an existence oracle over another tenant's tree.
+ */
+export interface BillableSitesRequest {
+    scope_node_ids: string[];
+    billable_site: boolean;
+}
+/**
+ * `POST /iam/clients/:id/admins` body (Doc 06 §5).
+ *
+ * `password` is chosen rather than generated, unlike a service-account secret.
+ * The distinction is what the credential is: a machine secret is never typed by
+ * anyone, so minting it removes a decision nobody benefits from making, whereas
+ * this one belongs to a person who is about to type it and change it. Doc 03 §7
+ * already governs its strength, and the tokenized reset of Doc 06 §3 is
+ * available from the moment the account exists.
+ *
+ * `scope_name` names the root of the tenant's org tree — the node every grant in
+ * this call covers. It defaults to the client's own name, which is what an
+ * operator means by it nine times out of ten; the tree beneath it is the
+ * client admin's to build (Doc 06 §6).
+ */
+export interface CreateClientAdminRequest {
+    email: string;
+    full_name: string;
+    password: string;
+    phone?: string;
+    scope_name?: string;
+}
+//# sourceMappingURL=clients.d.ts.map

package/dist/clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../src/clients.ts"],"names":[],"mappings":"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"}