@plantops/contracts 0.1.0

package/dist/grants.js

@@ -0,0 +1,13 @@
+/**
+ * Authorization contract — the resolved WHO × WHAT × WHERE answer every module
+ * consumes (Doc 04 §4–6).
+ */
+/** Redis key prefix for cached grants (Doc 04 §6). */
+export const GRANTS_CACHE_KEY_PREFIX = 'perms';
+/**
+ * `perms:{clientId}:{subjectType}:{subjectId}` — the cache key shape from
+ * Doc 04 §6. A function so IAM and every cache holder derive it identically.
+ */
+export function grantsCacheKey(clientId, subjectType, subjectId) {
+    return `${GRANTS_CACHE_KEY_PREFIX}:${clientId}:${subjectType}:${subjectId}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@plantops/contracts` — the public contract of the PlantOps IAM (Doc 08 §3).
+ *
+ * Framework-agnostic types and constants only, with **zero dependencies**, so
+ * every app, lib, and future operational module can import it without pulling
+ * anything else in. Keep it stable: changes here ripple to every consumer.
+ */
+export * from './audit.js';
+export * from './bindings.js';
+export * from './clients.js';
+export * from './constants.js';
+export * from './entitlements.js';
+export * from './errors.js';
+export * from './grants.js';
+export * from './jwt.js';
+export * from './manifest.js';
+export * from './nav.js';
+export * from './pagination.js';
+export * from './registry.js';
+export * from './roles.js';
+export * from './scopes.js';
+export * from './service-accounts.js';
+export * from './users.js';
+/**
+ * The compile-time assertion helpers (Doc 08 §7).
+ *
+ * Type-only and therefore free at runtime, and exported from the barrel since
+ * Session H6: `iam-api`'s `openapi/schemas.spec.ts` pins every response schema
+ * to the interface above it with `Expect<Equal<…>>`, and a helper that a second
+ * workspace consumer needs belongs on the public surface rather than behind a
+ * deep import.
+ */
+export * from './type-assertions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAE3B;;;;;;;;GAQG;AACH,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * `@plantops/contracts` — the public contract of the PlantOps IAM (Doc 08 §3).
+ *
+ * Framework-agnostic types and constants only, with **zero dependencies**, so
+ * every app, lib, and future operational module can import it without pulling
+ * anything else in. Keep it stable: changes here ripple to every consumer.
+ */
+export * from './audit.js';
+export * from './bindings.js';
+export * from './clients.js';
+export * from './constants.js';
+export * from './entitlements.js';
+export * from './errors.js';
+export * from './grants.js';
+export * from './jwt.js';
+export * from './manifest.js';
+export * from './nav.js';
+export * from './pagination.js';
+export * from './registry.js';
+export * from './roles.js';
+export * from './scopes.js';
+export * from './service-accounts.js';
+export * from './users.js';
+/**
+ * The compile-time assertion helpers (Doc 08 §7).
+ *
+ * Type-only and therefore free at runtime, and exported from the barrel since
+ * Session H6: `iam-api`'s `openapi/schemas.spec.ts` pins every response schema
+ * to the interface above it with `Expect<Equal<…>>`, and a helper that a second
+ * workspace consumer needs belongs on the public surface rather than behind a
+ * deep import.
+ */
+export * from './type-assertions.js';

package/dist/jwt.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Identity contract — the access-token claim shape (Doc 03 §2) and the token
+ * responses `/auth/*` returns (Doc 06 §3).
+ */
+/** WHO: a human `user` or a machine `service_account` (Doc 00 §2). */
+export declare const SubjectType: {
+    readonly USER: "user";
+    readonly SERVICE: "service";
+};
+export type SubjectType = (typeof SubjectType)[keyof typeof SubjectType];
+/**
+ * Access-token claims — exactly these seven, nothing more (Doc 03 §2).
+ *
+ * Permissions, roles and scope nodes are deliberately absent: they are resolved
+ * from `/iam/permissions/resolve` and cached, so a grant change takes effect on
+ * invalidation rather than on token expiry.
+ *
+ * Platform-admin status is *not* a claim either — it is derived from the
+ * subject's binding at the platform scope root (Doc 04 §10).
+ */
+export interface JwtClaims {
+    /** Issuer — always {@link IAM_ISSUER}. */
+    iss: string;
+    /** Subject: `user.id` or `service_account.id`. */
+    sub: string;
+    /** Subject type. */
+    sty: SubjectType;
+    /** Tenant — `client_id`. The *only* trustworthy source of tenant (Doc 07 §5). */
+    cid: string;
+    /** Session id, for revocation. Ephemeral for service tokens (Doc 03 §5). */
+    sid: string;
+    /** Issued-at, epoch seconds. */
+    iat: number;
+    /** Expiry, epoch seconds. */
+    exp: number;
+}
+/**
+ * The claim names an access token may carry, in Doc 03 §2 order. Used by the
+ * token service's shape test — an extra claim is a spec violation, not a
+ * harmless addition.
+ */
+export declare const JWT_CLAIM_KEYS: readonly ["iss", "sub", "sty", "cid", "sid", "iat", "exp"];
+export type JwtClaimKey = (typeof JWT_CLAIM_KEYS)[number];
+/**
+ * Claims a verifier **accepts without requiring or interpreting** (ADR 0005 §5.1).
+ *
+ * Not part of {@link JwtClaims}, and deliberately not: nothing reads these, no
+ * decision branches on them, and `readAccessTokenClaims` drops them rather than
+ * returning them. A caller cannot accidentally consume one.
+ *
+ * ## Why `aud` is here while the IAM mints no `aud`
+ *
+ * The claim set is closed in both directions (Doc 03 §2), and the *accepting*
+ * half of that is the half this repository cannot migrate. Every consumer
+ * verifies locally with the published `@plantops/auth-kit`, so the day the IAM
+ * mints a claim an older verifier has never heard of, that verifier rejects
+ * **every** token — a total outage rather than a degradation.
+ *
+ * Admitting `aud` now costs nothing today and buys the option to reconsider ADR
+ * 0005 §3.3 later without a strictly-ordered upgrade across repositories this
+ * one does not control. After `libs-v0.1.0` the option is gone, which is why
+ * ADR 0005 §5.1 gave it a deadline rather than a backlog entry.
+ *
+ * Signing is **not** relaxed: `assertExactClaims` still refuses an eighth claim,
+ * so this changes what a token may contain, not what this IAM puts in one. The
+ * asymmetry is the whole design — the verifier is un-migratable, the signer is
+ * one deploy.
+ */
+export declare const JWT_TOLERATED_CLAIM_KEYS: readonly ["aud"];
+export type JwtToleratedClaimKey = (typeof JWT_TOLERATED_CLAIM_KEYS)[number];
+/** `POST /auth/login` body (Doc 06 §3). */
+export interface LoginRequest {
+    email: string;
+    password: string;
+    client_slug: string;
+}
+/** `POST /auth/refresh` body (Doc 06 §3). */
+export interface RefreshRequest {
+    refresh_token: string;
+}
+/** `POST /auth/token` body — client-credentials exchange (Doc 03 §5). */
+export interface ServiceTokenRequest {
+    account_key: string;
+    account_secret: string;
+}
+/** Login / refresh response (Doc 06 §3). */
+export interface TokenPairResponse {
+    access_token: string;
+    refresh_token: string;
+    /** Access-token lifetime in seconds. */
+    expires_in: number;
+}
+/** Service-account token response — no refresh token by design (Doc 03 §5). */
+export interface AccessTokenResponse {
+    access_token: string;
+    expires_in: number;
+}
+/**
+ * One row of `GET /auth/sessions` (Doc 06 §3).
+ *
+ * Note what is absent: `refresh_token_hash`. A session list is a security
+ * screen — "where am I logged in, and what do I want to kill" — and it is
+ * rendered in a browser. The hash is the credential's stored form; nothing that
+ * can be replayed or brute-forced belongs in a response that exists to *show*
+ * sessions (Doc 10 §8).
+ */
+export interface SessionDTO {
+    /** The `sid` claim of tokens issued for this session. */
+    id: string;
+    /** e.g. "Gate-3 Terminal" — what makes the list actionable. */
+    device_label: string | null;
+    /** ISO-8601. */
+    issued_at: string;
+    expires_at: string;
+    /** Set once revoked, and never cleared. */
+    revoked_at: string | null;
+    /**
+     * True for the session the calling token belongs to.
+     *
+     * Without it a user revoking "everything else" has no way to tell which row
+     * is the browser they are looking at — and logging yourself out while trying
+     * to log a lost terminal out is the mistake this flag exists to prevent.
+     */
+    current: boolean;
+}
+/**
+ * `POST /iam/introspect` response (Doc 06 §11). Inactive tokens carry no
+ * identity fields — never leak subject data for a token that failed
+ * verification.
+ */
+export type IntrospectResponse = {
+    active: false;
+} | {
+    active: true;
+    sub: string;
+    sty: SubjectType;
+    cid: string;
+    sid: string;
+};
+/** One entry of `/iam/.well-known/jwks.json` (Doc 03 §1). */
+export interface JwkDTO {
+    kty: string;
+    use?: string;
+    alg?: string;
+    kid: string;
+    n?: string;
+    e?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+}
+export interface JwksResponse {
+    keys: JwkDTO[];
+}
+//# sourceMappingURL=jwt.d.ts.map

package/dist/jwt.d.ts.map

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

package/dist/jwt.js

@@ -0,0 +1,49 @@
+/**
+ * Identity contract — the access-token claim shape (Doc 03 §2) and the token
+ * responses `/auth/*` returns (Doc 06 §3).
+ */
+/** WHO: a human `user` or a machine `service_account` (Doc 00 §2). */
+export const SubjectType = {
+    USER: 'user',
+    SERVICE: 'service',
+};
+/**
+ * The claim names an access token may carry, in Doc 03 §2 order. Used by the
+ * token service's shape test — an extra claim is a spec violation, not a
+ * harmless addition.
+ */
+export const JWT_CLAIM_KEYS = [
+    'iss',
+    'sub',
+    'sty',
+    'cid',
+    'sid',
+    'iat',
+    'exp',
+];
+/**
+ * Claims a verifier **accepts without requiring or interpreting** (ADR 0005 §5.1).
+ *
+ * Not part of {@link JwtClaims}, and deliberately not: nothing reads these, no
+ * decision branches on them, and `readAccessTokenClaims` drops them rather than
+ * returning them. A caller cannot accidentally consume one.
+ *
+ * ## Why `aud` is here while the IAM mints no `aud`
+ *
+ * The claim set is closed in both directions (Doc 03 §2), and the *accepting*
+ * half of that is the half this repository cannot migrate. Every consumer
+ * verifies locally with the published `@plantops/auth-kit`, so the day the IAM
+ * mints a claim an older verifier has never heard of, that verifier rejects
+ * **every** token — a total outage rather than a degradation.
+ *
+ * Admitting `aud` now costs nothing today and buys the option to reconsider ADR
+ * 0005 §3.3 later without a strictly-ordered upgrade across repositories this
+ * one does not control. After `libs-v0.1.0` the option is gone, which is why
+ * ADR 0005 §5.1 gave it a deadline rather than a backlog entry.
+ *
+ * Signing is **not** relaxed: `assertExactClaims` still refuses an eighth claim,
+ * so this changes what a token may contain, not what this IAM puts in one. The
+ * asymmetry is the whole design — the verifier is un-migratable, the signer is
+ * one deploy.
+ */
+export const JWT_TOLERATED_CLAIM_KEYS = ['aud'];

package/dist/lib/contracts.d.ts

@@ -0,0 +1,2 @@
+export declare function contracts(): string;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/lib/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/lib/contracts.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,IAAI,MAAM,CAElC"}

package/dist/lib/contracts.js

@@ -0,0 +1,3 @@
+export function contracts() {
+    return 'contracts';
+}

package/dist/manifest.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Application manifest — the declarative document an application ships to
+ * register (and later evolve) its permission and navigation catalog
+ * (Doc 02 §2).
+ *
+ * Uploading a manifest is an **upsert keyed by natural key** (`application.key`
+ * + node/permission `key`): re-uploading is idempotent, changed labels update in
+ * place, and keys absent from a re-upload soft-deactivate rather than delete
+ * (Doc 02 §7).
+ *
+ * ## Two naming conventions in one file, on purpose
+ *
+ * The manifest *document* is camelCase (`sortOrder`, `isPublic`). It is a
+ * hand-authored JSON file that ships with an application, not an API body, and
+ * this shape is the one the contract has published since Session 1.
+ *
+ * The *response* types below are snake_case, matching {@link ApplicationDTO} and
+ * every other shape Doc 06 §3 writes out. A convention that changes between two
+ * endpoints of the same API is worse than either convention — and the diff is an
+ * API response, whatever the document that produced it looks like.
+ */
+import type { NavNodeKind } from './nav.js';
+export interface ManifestPermission {
+    /** Namespaced `app.resource.action`, unique within the application. */
+    key: string;
+    name: string;
+    description?: string;
+}
+export interface ManifestNavNode {
+    kind: NavNodeKind;
+    /** Unique within the application; the upsert's natural key. */
+    key: string;
+    label: string;
+    /** Frontend path. Omit for pure containers. */
+    route?: string;
+    /** Icon key resolved by the frontend's icon set (Doc 05 §7). */
+    icon?: string;
+    sortOrder?: number;
+    /**
+     * Leaf-only opt-in making an *unmapped* leaf visible to anyone who can see
+     * the app. Defaults to `false` — unmapped means hidden (Doc 05 §3).
+     */
+    isPublic?: boolean;
+    /**
+     * Permission keys gating this node, OR semantics — becomes `menu_permission`
+     * rows (Doc 01 §4.4).
+     */
+    requires?: string[];
+    children?: ManifestNavNode[];
+}
+export interface ApplicationManifest {
+    /** Machine key of the application, e.g. `gatepass` (Doc 01 §3.1). */
+    key: string;
+    name: string;
+    description?: string;
+    permissions: ManifestPermission[];
+    nav: ManifestNavNode[];
+}
+/**
+ * What an upsert did to one kind of catalog row, by natural key.
+ *
+ * Keys rather than counts, because both consumers need the names: Doc 09 §2.1's
+ * preview screen shows the operator *what* is about to change, and the audit
+ * payload has to answer "when did this key appear, and when did it go" long
+ * after the manifest that caused it was overwritten.
+ *
+ * There is no `deleted`. Removal from a manifest soft-deactivates (Doc 02 §7) —
+ * `role_permission` rows and audit payloads still name these keys, and a hard
+ * delete would revoke grants with no record of what was revoked.
+ *
+ * Reactivation of a key that came back is an `updated`, with `is_active` among
+ * the fields that moved.
+ */
+export interface ManifestEntityDiff {
+    created: string[];
+    updated: string[];
+    deactivated: string[];
+}
+/** One nav node and the permission keys mapped to (or unmapped from) it. */
+export interface ManifestMappingChange {
+    nav_key: string;
+    permission_keys: string[];
+}
+/**
+ * `menu_permission` movement, grouped by nav node.
+ *
+ * Grouped rather than listed pair by pair for the reason the mapping audit
+ * records are: a node's gate is one fact about that node, and a flat pair list
+ * says the same thing in `nodes × permissions` lines.
+ */
+export interface ManifestMappingDiff {
+    mapped: ManifestMappingChange[];
+    unmapped: ManifestMappingChange[];
+}
+/** Fields of the `application` row itself the manifest moved (`name`, `description`). */
+export interface ManifestApplicationDiff {
+    key: string;
+    changed: string[];
+}
+/**
+ * The complete difference between a manifest and the catalog it is applied to.
+ *
+ * Computed before anything is written, which is what lets Session 29 preview it
+ * and this session audit it — the same value, from the same function.
+ */
+export interface ManifestDiff {
+    application: ManifestApplicationDiff;
+    permissions: ManifestEntityDiff;
+    nav: ManifestEntityDiff;
+    menu_permissions: ManifestMappingDiff;
+}
+/** `POST /iam/applications/:id/manifest[?dryRun=true]` (Doc 06 §4). */
+export interface ManifestUpsertResponse {
+    application_id: string;
+    /**
+     * `true` when the call only *computed* the diff — `?dryRun=true`, the preview
+     * Doc 09 §2.1 shows an operator before they confirm an upload.
+     *
+     * A preview writes nothing: no catalog rows, no audit record, no cache
+     * invalidation. It is otherwise the same answer the real upload gives, from
+     * the same function against the same snapshot, which is what lets the screen
+     * promise that confirming applies what was previewed.
+     */
+    dry_run: boolean;
+    /**
+     * `false` when the manifest described exactly what was already there — and,
+     * on a dry run, that applying it *would* change nothing.
+     *
+     * A no-op upsert writes nothing at all — no rows, no audit record — so this
+     * flag is the only way a caller can tell an idempotent re-upload from a
+     * first one without diffing the diff itself.
+     */
+    changed: boolean;
+    diff: ManifestDiff;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,GAAG,EAAE,eAAe,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAED,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,uBAAuB,CAAC;IACrC,WAAW,EAAE,kBAAkB,CAAC;IAChC,GAAG,EAAE,kBAAkB,CAAC;IACxB,gBAAgB,EAAE,mBAAmB,CAAC;CACvC;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;CACpB"}

package/dist/manifest.js

@@ -0,0 +1,22 @@
+/**
+ * Application manifest — the declarative document an application ships to
+ * register (and later evolve) its permission and navigation catalog
+ * (Doc 02 §2).
+ *
+ * Uploading a manifest is an **upsert keyed by natural key** (`application.key`
+ * + node/permission `key`): re-uploading is idempotent, changed labels update in
+ * place, and keys absent from a re-upload soft-deactivate rather than delete
+ * (Doc 02 §7).
+ *
+ * ## Two naming conventions in one file, on purpose
+ *
+ * The manifest *document* is camelCase (`sortOrder`, `isPublic`). It is a
+ * hand-authored JSON file that ships with an application, not an API body, and
+ * this shape is the one the contract has published since Session 1.
+ *
+ * The *response* types below are snake_case, matching {@link ApplicationDTO} and
+ * every other shape Doc 06 §3 writes out. A convention that changes between two
+ * endpoints of the same API is worse than either convention — and the diff is an
+ * API response, whatever the document that produced it looks like.
+ */
+export {};

package/dist/nav.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Navigation contract — the pruned menu tree `GET /iam/navigation` returns
+ * (Doc 05 §4). The frontend renders this directly; it keeps no menu constants
+ * of its own (Doc 05 §7).
+ */
+/** Depth discriminator on the self-referencing `nav_node` table (Doc 01 §3.3). */
+export declare const NavNodeKind: {
+    readonly MODULE: "module";
+    readonly MENU: "menu";
+    readonly SUB_MENU: "sub_menu";
+};
+export type NavNodeKind = (typeof NavNodeKind)[keyof typeof NavNodeKind];
+/**
+ * The three kinds as a list, in the order the Postgres enum declares its labels
+ * (migration 0001).
+ *
+ * Exists for the same reason `SERVICE_ACCOUNT_STATUS_VALUES` does: a request
+ * schema needs an array to build a closed enum from, and deriving it from the
+ * object above with `Object.values` would lose the tuple type that makes
+ * `z.enum` produce a `NavNodeKind` rather than a `string`.
+ */
+export declare const NAV_NODE_KIND_VALUES: readonly ["module", "menu", "sub_menu"];
+/**
+ * A node in the resolved tree. Only visible nodes are present: leaves the
+ * subject holds no mapped permission for are pruned, and containers left
+ * without a visible descendant are pruned with them (Doc 05 §3).
+ */
+export interface NavNodeDTO {
+    id: string;
+    kind: NavNodeKind;
+    key: string;
+    label: string;
+    /** Frontend path; absent on pure containers. */
+    route?: string | null;
+    /** Icon *key* — the frontend maps it to its own icon set (Doc 05 §7). */
+    icon?: string | null;
+    children: NavNodeDTO[];
+}
+export interface ApplicationSummaryDTO {
+    id: string;
+    key: string;
+    name: string;
+}
+/**
+ * `GET /iam/navigation?applicationId=` → one application's tree.
+ * `GET /iam/navigation` (no id) → the cross-application shell, one top-level
+ * node per enabled application, with `application: null` (Doc 05 §4).
+ */
+export interface NavigationResponse {
+    application: ApplicationSummaryDTO | null;
+    tree: NavNodeDTO[];
+}
+//# sourceMappingURL=nav.d.ts.map

package/dist/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../src/nav.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kFAAkF;AAClF,eAAO,MAAM,WAAW;;;;CAId,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,yCAIU,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC1C,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB"}

package/dist/nav.js

@@ -0,0 +1,25 @@
+/**
+ * Navigation contract — the pruned menu tree `GET /iam/navigation` returns
+ * (Doc 05 §4). The frontend renders this directly; it keeps no menu constants
+ * of its own (Doc 05 §7).
+ */
+/** Depth discriminator on the self-referencing `nav_node` table (Doc 01 §3.3). */
+export const NavNodeKind = {
+    MODULE: 'module',
+    MENU: 'menu',
+    SUB_MENU: 'sub_menu',
+};
+/**
+ * The three kinds as a list, in the order the Postgres enum declares its labels
+ * (migration 0001).
+ *
+ * Exists for the same reason `SERVICE_ACCOUNT_STATUS_VALUES` does: a request
+ * schema needs an array to build a closed enum from, and deriving it from the
+ * object above with `Object.values` would lose the tuple type that makes
+ * `z.enum` produce a `NavNodeKind` rather than a `string`.
+ */
+export const NAV_NODE_KIND_VALUES = [
+    NavNodeKind.MODULE,
+    NavNodeKind.MENU,
+    NavNodeKind.SUB_MENU,
+];

package/dist/pagination.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pagination contract — `?page=&limit=` → `{ data, page, limit, total }`
+ * (Doc 06 §1).
+ *
+ * Note the deliberate exception: `/iam/permissions/resolve` is **not**
+ * paginated. A subject's grant set is one cacheable unit, bounded instead by
+ * path minimization and the optional `applicationId` filter (Doc 06 §11).
+ */
+export declare const DEFAULT_PAGE = 1;
+export declare const DEFAULT_PAGE_SIZE = 25;
+export declare const MAX_PAGE_SIZE = 100;
+/** Query parameters accepted by every list endpoint. */
+export interface PaginationQuery {
+    page?: number;
+    limit?: number;
+}
+/** The envelope every list endpoint returns. */
+export interface Paginated<T> {
+    data: T[];
+    page: number;
+    limit: number;
+    /** Total matching rows, not the length of `data`. */
+    total: number;
+}
+/** Normalizes user input to a valid, bounded `(page, limit)` pair. */
+export declare function normalizePagination(query?: PaginationQuery): Required<PaginationQuery>;
+export declare function paginated<T>(data: T[], total: number, query?: PaginationQuery): Paginated<T>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CACjC,KAAK,GAAE,eAAoB,GAC1B,QAAQ,CAAC,eAAe,CAAC,CAK3B;AAQD,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,eAAoB,GAC1B,SAAS,CAAC,CAAC,CAAC,CAGd"}

package/dist/pagination.js

@@ -0,0 +1,27 @@
+/**
+ * Pagination contract — `?page=&limit=` → `{ data, page, limit, total }`
+ * (Doc 06 §1).
+ *
+ * Note the deliberate exception: `/iam/permissions/resolve` is **not**
+ * paginated. A subject's grant set is one cacheable unit, bounded instead by
+ * path minimization and the optional `applicationId` filter (Doc 06 §11).
+ */
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_PAGE_SIZE = 25;
+export const MAX_PAGE_SIZE = 100;
+/** Normalizes user input to a valid, bounded `(page, limit)` pair. */
+export function normalizePagination(query = {}) {
+    const page = Math.max(DEFAULT_PAGE, toInt(query.page, DEFAULT_PAGE));
+    const requested = toInt(query.limit, DEFAULT_PAGE_SIZE);
+    const limit = Math.min(MAX_PAGE_SIZE, Math.max(1, requested));
+    return { page, limit };
+}
+function toInt(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.trunc(value)
+        : fallback;
+}
+export function paginated(data, total, query = {}) {
+    const { page, limit } = normalizePagination(query);
+    return { data, page, limit, total };
+}