@plantops/contracts 0.1.0

package/dist/clients.js

@@ -0,0 +1,49 @@
+/**
+ * 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 const ClientStatus = {
+    ACTIVE: 'active',
+    SUSPENDED: 'suspended',
+};
+export const CLIENT_STATUS_VALUES = [
+    ClientStatus.ACTIVE,
+    ClientStatus.SUSPENDED,
+];

package/dist/constants.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared constants every project agrees on. Values that IAM and consuming
+ * modules must not disagree about live here (Doc 08 §3), never duplicated in a
+ * service.
+ *
+ * These are *defaults and invariants*, not deployment configuration: anything an
+ * operator may retune per environment is validated in `@plantops/config`, which
+ * uses these values as its defaults.
+ */
+/** `iss` claim on every token the IAM signs (Doc 03 §2). */
+export declare const IAM_ISSUER = "plantops-iam";
+/** Base path for the IAM surface (Doc 06 §1). */
+export declare const IAM_ROUTE_PREFIX = "/iam";
+/** Base path for the authentication surface (Doc 06 §1). */
+export declare const AUTH_ROUTE_PREFIX = "/auth";
+/**
+ * Leeway applied to `exp`/`iat`/`nbf` checks in the IAM *and* in every consuming
+ * module, absorbing clock drift between signer and verifiers (Doc 03 §6).
+ * Shared so verifiers cannot drift apart.
+ */
+export declare const CLOCK_SKEW_LEEWAY_SECONDS = 60;
+/**
+ * The one signature algorithm the IAM issues and accepts (Doc 03 §1).
+ *
+ * Pinned as a constant because verification must never take the algorithm from
+ * the token being verified. A verifier that honours the incoming `alg` header
+ * accepts `alg: "none"`, and accepts an HS256 token forged with the *public*
+ * key as the HMAC secret — the two classic JWT breaks, both of which look like
+ * ordinary success. Comparing the header against this value and rejecting
+ * anything else closes them.
+ */
+export declare const JWT_SIGNING_ALGORITHM = "RS256";
+/** Smallest RSA modulus the IAM will sign or verify with. */
+export declare const JWT_MIN_RSA_KEY_BITS = 2048;
+/**
+ * `max-age` on the JWKS response (Doc 03 §1 step 2).
+ *
+ * Rotation says to wait for JWKS propagation — "allow at least one cache TTL" —
+ * before switching signers. That step is only actionable if the TTL is a known
+ * number, so the endpoint publishes this one and the rotation tool reads the
+ * same constant when it computes the earliest safe activation time. Changing it
+ * changes both ends together.
+ */
+export declare const JWKS_CACHE_MAX_AGE_SECONDS = 300;
+/** Human access-token lifetime — 15 min (Doc 03 §1). */
+export declare const ACCESS_TOKEN_TTL_SECONDS = 900;
+/** Refresh-token lifetime — 7 days, inside the 7–30 day band (Doc 03 §1). */
+export declare const REFRESH_TOKEN_TTL_SECONDS = 604800;
+/**
+ * Service-account access-token lifetime — 5 min. Doc 03 §5 caps these at ≤5 min
+ * because an ephemeral `sid` cannot be revoked mid-token; the TTL *is* the
+ * revocation window.
+ */
+export declare const SERVICE_ACCESS_TOKEN_TTL_SECONDS = 300;
+export declare const SERVICE_ACCESS_TOKEN_MAX_TTL_SECONDS = 300;
+/**
+ * Window during which the immediately-previous refresh token replays
+ * idempotently instead of being treated as compromise, so two legitimate
+ * clients refreshing at once do not kill a live session (Doc 03 §4: 10–30 s).
+ */
+export declare const REFRESH_REUSE_GRACE_SECONDS = 15;
+export declare const REFRESH_REUSE_GRACE_MIN_SECONDS = 10;
+export declare const REFRESH_REUSE_GRACE_MAX_SECONDS = 30;
+/**
+ * Grants-cache TTL — the safety net behind invalidation, and the staleness bound
+ * on `role_binding.expires_at` (Doc 01 §4.5, Doc 04 §6: ≤10 min).
+ */
+export declare const GRANTS_CACHE_TTL_SECONDS = 600;
+export declare const GRANTS_CACHE_MAX_TTL_SECONDS = 600;
+/**
+ * ltree labels are `n_` + the node's UUID hex — id-derived, never name-derived,
+ * so a rename never rewrites a path (Doc 01 §3.5).
+ */
+export declare const SCOPE_PATH_LABEL_PREFIX = "n_";
+/** Permission namespaces for the two administrative tiers (Doc 02 §1). */
+export declare const PLATFORM_PERMISSION_NAMESPACE = "iam.platform";
+export declare const CLIENT_PERMISSION_NAMESPACE = "iam.client";
+/** Redis pub/sub channel carrying grant-invalidation events (Doc 04 §7). */
+export declare const PERMS_INVALIDATED_CHANNEL = "perms.invalidated";
+/**
+ * Key namespace for the revoked-`sid` cache (Doc 03 §6).
+ *
+ * Shared rather than private to the IAM because the IAM *writes* these keys and
+ * every consuming module *reads* them: a module that guesses a different prefix
+ * finds no revocations and honours force-logout never. One entry per revoked
+ * session, expiring on its own — see {@link revokedSessionKey}.
+ */
+export declare const REVOKED_SESSION_KEY_PREFIX = "revoked-sid:";
+/** The revoked-`sid` cache key for a session id. */
+export declare function revokedSessionKey(sessionId: string): string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,MAAM,CAAC;AACpD,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,iBAAiB,CAAC;AAC5D,eAAO,MAAM,2BAA2B,eAAe,CAAC;AAExD,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AAEzD,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/constants.js

@@ -0,0 +1,92 @@
+/**
+ * Shared constants every project agrees on. Values that IAM and consuming
+ * modules must not disagree about live here (Doc 08 §3), never duplicated in a
+ * service.
+ *
+ * These are *defaults and invariants*, not deployment configuration: anything an
+ * operator may retune per environment is validated in `@plantops/config`, which
+ * uses these values as its defaults.
+ */
+/** `iss` claim on every token the IAM signs (Doc 03 §2). */
+export const IAM_ISSUER = 'plantops-iam';
+/** Base path for the IAM surface (Doc 06 §1). */
+export const IAM_ROUTE_PREFIX = '/iam';
+/** Base path for the authentication surface (Doc 06 §1). */
+export const AUTH_ROUTE_PREFIX = '/auth';
+/**
+ * Leeway applied to `exp`/`iat`/`nbf` checks in the IAM *and* in every consuming
+ * module, absorbing clock drift between signer and verifiers (Doc 03 §6).
+ * Shared so verifiers cannot drift apart.
+ */
+export const CLOCK_SKEW_LEEWAY_SECONDS = 60;
+/**
+ * The one signature algorithm the IAM issues and accepts (Doc 03 §1).
+ *
+ * Pinned as a constant because verification must never take the algorithm from
+ * the token being verified. A verifier that honours the incoming `alg` header
+ * accepts `alg: "none"`, and accepts an HS256 token forged with the *public*
+ * key as the HMAC secret — the two classic JWT breaks, both of which look like
+ * ordinary success. Comparing the header against this value and rejecting
+ * anything else closes them.
+ */
+export const JWT_SIGNING_ALGORITHM = 'RS256';
+/** Smallest RSA modulus the IAM will sign or verify with. */
+export const JWT_MIN_RSA_KEY_BITS = 2048;
+/**
+ * `max-age` on the JWKS response (Doc 03 §1 step 2).
+ *
+ * Rotation says to wait for JWKS propagation — "allow at least one cache TTL" —
+ * before switching signers. That step is only actionable if the TTL is a known
+ * number, so the endpoint publishes this one and the rotation tool reads the
+ * same constant when it computes the earliest safe activation time. Changing it
+ * changes both ends together.
+ */
+export const JWKS_CACHE_MAX_AGE_SECONDS = 300;
+/** Human access-token lifetime — 15 min (Doc 03 §1). */
+export const ACCESS_TOKEN_TTL_SECONDS = 900;
+/** Refresh-token lifetime — 7 days, inside the 7–30 day band (Doc 03 §1). */
+export const REFRESH_TOKEN_TTL_SECONDS = 604_800;
+/**
+ * Service-account access-token lifetime — 5 min. Doc 03 §5 caps these at ≤5 min
+ * because an ephemeral `sid` cannot be revoked mid-token; the TTL *is* the
+ * revocation window.
+ */
+export const SERVICE_ACCESS_TOKEN_TTL_SECONDS = 300;
+export const SERVICE_ACCESS_TOKEN_MAX_TTL_SECONDS = 300;
+/**
+ * Window during which the immediately-previous refresh token replays
+ * idempotently instead of being treated as compromise, so two legitimate
+ * clients refreshing at once do not kill a live session (Doc 03 §4: 10–30 s).
+ */
+export const REFRESH_REUSE_GRACE_SECONDS = 15;
+export const REFRESH_REUSE_GRACE_MIN_SECONDS = 10;
+export const REFRESH_REUSE_GRACE_MAX_SECONDS = 30;
+/**
+ * Grants-cache TTL — the safety net behind invalidation, and the staleness bound
+ * on `role_binding.expires_at` (Doc 01 §4.5, Doc 04 §6: ≤10 min).
+ */
+export const GRANTS_CACHE_TTL_SECONDS = 600;
+export const GRANTS_CACHE_MAX_TTL_SECONDS = 600;
+/**
+ * ltree labels are `n_` + the node's UUID hex — id-derived, never name-derived,
+ * so a rename never rewrites a path (Doc 01 §3.5).
+ */
+export const SCOPE_PATH_LABEL_PREFIX = 'n_';
+/** Permission namespaces for the two administrative tiers (Doc 02 §1). */
+export const PLATFORM_PERMISSION_NAMESPACE = 'iam.platform';
+export const CLIENT_PERMISSION_NAMESPACE = 'iam.client';
+/** Redis pub/sub channel carrying grant-invalidation events (Doc 04 §7). */
+export const PERMS_INVALIDATED_CHANNEL = 'perms.invalidated';
+/**
+ * Key namespace for the revoked-`sid` cache (Doc 03 §6).
+ *
+ * Shared rather than private to the IAM because the IAM *writes* these keys and
+ * every consuming module *reads* them: a module that guesses a different prefix
+ * finds no revocations and honours force-logout never. One entry per revoked
+ * session, expiring on its own — see {@link revokedSessionKey}.
+ */
+export const REVOKED_SESSION_KEY_PREFIX = 'revoked-sid:';
+/** The revoked-`sid` cache key for a session id. */
+export function revokedSessionKey(sessionId) {
+    return `${REVOKED_SESSION_KEY_PREFIX}${sessionId}`;
+}

package/dist/entitlements.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Entitlement contract — what a tenant is entitled to, readable by the tenant
+ * (`GET /iam/entitlements`).
+ *
+ * ## Why this exists next to `/iam/licence`
+ *
+ * `LicenceView` answers one question — when does this deployment's term run
+ * out — and answers it for a console header. It carries no ceilings and no
+ * per-application view, so a consuming module that needed to know "is the
+ * postmortem module enabled for this client, until when, and how many seats"
+ * had two options, both bad: embed `iam.platform.*` credentials in every
+ * consumer instance to call `GET /iam/clients/:id/applications`, or go
+ * without. This is the third option.
+ *
+ * `/iam/licence` stays exactly as it is. It is a shipped contract with a
+ * consumer, and this is a superset rather than a replacement.
+ *
+ * ## The IAM reports; it does not enforce
+ *
+ * Nothing here is an authorization decision. An application whose term has
+ * passed still resolves grants and still appears in navigation — see
+ * `apps/iam-api/src/licence/licence.guard.ts`, which exempts
+ * `/iam/permissions/resolve` and `/iam/introspect` from expiry blocking by
+ * name, on the grounds that an IAM which stops issuing tokens is a plant that
+ * stops running.
+ *
+ * So {@link ApplicationEntitlement.expired} is information a consumer acts on,
+ * and a consumer that ignores it has bought nothing. Doc 12 states the
+ * obligation normatively.
+ *
+ * ## This is not the grants cache
+ *
+ * Resolved grants invalidate on a `(client, subject)` version counter, exactly,
+ * on write. Entitlement state cannot: **nothing writes at the moment a term
+ * expires**, so no counter moves and no invalidation fires. It goes stale on a
+ * clock instead, which is what {@link EntitlementsView.as_of} is for.
+ *
+ * Caching this against the grants version counter produces a value that is
+ * wrong forever rather than briefly. Doc 12 forbids it in those words.
+ *
+ * Field naming is snake_case, matching every other published shape here.
+ */
+/**
+ * The tenant-wide ceiling and how much of it is spent.
+ *
+ * `null` on any ceiling means unlimited — the reading every pre-licence
+ * deployment relies on (migration 0020). The counts are live at the moment of
+ * the read, not cached: they sit beside a write that is about to be allowed or
+ * refused, and a stale "you are under your limit" is worse than counting.
+ */
+export interface TenantEntitlement {
+    /**
+     * The **effective** term: whichever of the signed licence and the client
+     * row's subscription column expires first. `null` when nothing expires.
+     */
+    expires_at: string | null;
+    /** True once `expires_at` has passed. Administrative writes are blocked. */
+    expired: boolean;
+    max_users: number | null;
+    max_sites: number | null;
+    /** Users in `active` status. The number `max_users` is compared against. */
+    active_users: number;
+    /**
+     * Scope nodes flagged `billable_site`.
+     *
+     * A platform-set flag, deliberately not derived from `scope_node.kind`:
+     * kind is tenant-supplied text (ADR 0002 §6), and a meter the customer can
+     * rename away is not a meter. See migration 0020.
+     */
+    billable_sites: number;
+}
+/** One enabled application's own entitlement (`client_application`). */
+export interface ApplicationEntitlement {
+    /** The application's stable key, e.g. `gatepass`. */
+    key: string;
+    name: string;
+    /**
+     * The tenant's switch for this application. A disabled application resolves
+     * no grants at all — this one *is* enforced, in `resolver.service.ts`.
+     */
+    enabled: boolean;
+    /** This application's own term, independent of the tenant's. */
+    expires_at: string | null;
+    /**
+     * True once this application's own term has passed.
+     *
+     * **Nothing in the IAM acts on this.** Grants still resolve and navigation
+     * still renders; the consuming module is what must refuse. See the header.
+     */
+    expired: boolean;
+    max_users: number | null;
+    max_sites: number | null;
+}
+/** `GET /iam/entitlements` (Doc 12). */
+export interface EntitlementsView {
+    /**
+     * When this snapshot was taken.
+     *
+     * Consumers bound their cache staleness against this rather than against
+     * their own clock, because the interesting skew is between the reader and
+     * the IAM, not between the reader and real time.
+     */
+    as_of: string;
+    tenant: TenantEntitlement;
+    /**
+     * Every application enabled for this client, plus any that were enabled and
+     * later switched off — a disabled row is preserved, not deleted (Doc 02 §7),
+     * and a consumer that vanished from this list could not tell "never had it"
+     * from "lost it".
+     */
+    applications: ApplicationEntitlement[];
+}
+/**
+ * `GET /iam/licence` (Doc 11 §10) — the effective term, and nothing else.
+ *
+ * Predates {@link EntitlementsView} and is kept beside it rather than folded
+ * into it: the console header that renders a thirty-day warning wants one date
+ * and should not pay for a per-application read to get it.
+ *
+ * The term reported is the effective one — whichever of the signed licence and
+ * the client row's subscription column expires first. Unlike the per-module
+ * terms in {@link ApplicationEntitlement}, this one **is** enforced: once past,
+ * administrative writes are refused, while `/auth/*`,
+ * `/iam/permissions/resolve` and `/iam/introspect` keep working.
+ */
+export interface LicenceView {
+    /** Whether any term applies at all — a licence file, a subscription, or both. */
+    configured: boolean;
+    expired: boolean;
+    /** ISO instant of the effective term; `null` when nothing expires. */
+    expires_at: string | null;
+    /** Whole days to the effective term; negative once past. */
+    days_remaining: number | null;
+}
+//# sourceMappingURL=entitlements.d.ts.map

package/dist/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,EAAE,sBAAsB,EAAE,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B"}

package/dist/entitlements.js

@@ -0,0 +1,43 @@
+/**
+ * Entitlement contract — what a tenant is entitled to, readable by the tenant
+ * (`GET /iam/entitlements`).
+ *
+ * ## Why this exists next to `/iam/licence`
+ *
+ * `LicenceView` answers one question — when does this deployment's term run
+ * out — and answers it for a console header. It carries no ceilings and no
+ * per-application view, so a consuming module that needed to know "is the
+ * postmortem module enabled for this client, until when, and how many seats"
+ * had two options, both bad: embed `iam.platform.*` credentials in every
+ * consumer instance to call `GET /iam/clients/:id/applications`, or go
+ * without. This is the third option.
+ *
+ * `/iam/licence` stays exactly as it is. It is a shipped contract with a
+ * consumer, and this is a superset rather than a replacement.
+ *
+ * ## The IAM reports; it does not enforce
+ *
+ * Nothing here is an authorization decision. An application whose term has
+ * passed still resolves grants and still appears in navigation — see
+ * `apps/iam-api/src/licence/licence.guard.ts`, which exempts
+ * `/iam/permissions/resolve` and `/iam/introspect` from expiry blocking by
+ * name, on the grounds that an IAM which stops issuing tokens is a plant that
+ * stops running.
+ *
+ * So {@link ApplicationEntitlement.expired} is information a consumer acts on,
+ * and a consumer that ignores it has bought nothing. Doc 12 states the
+ * obligation normatively.
+ *
+ * ## This is not the grants cache
+ *
+ * Resolved grants invalidate on a `(client, subject)` version counter, exactly,
+ * on write. Entitlement state cannot: **nothing writes at the moment a term
+ * expires**, so no counter moves and no invalidation fires. It goes stale on a
+ * clock instead, which is what {@link EntitlementsView.as_of} is for.
+ *
+ * Caching this against the grants version counter produces a value that is
+ * wrong forever rather than briefly. Doc 12 forbids it in those words.
+ *
+ * Field naming is snake_case, matching every other published shape here.
+ */
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Error contract — the envelope and the code table from Doc 06 §2.
+ *
+ * The table there is authoritative and closed: adding a code is a spec change,
+ * not an implementation detail, because consumers (`iam-client`, admin-web,
+ * every future module) branch on these values.
+ */
+export declare const IamErrorCode: {
+    /** 400 — request failed validation; see `details` for the offending fields. */
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** 401 — no (or unverifiable) bearer token. */
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    /** 401 — login rejected. Generic by design: never hints at user existence. */
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
+    /** 403 — subject does not hold the required permission. */
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    /** 403 — permission held, but not at a scope node covering the target. */
+    readonly SCOPE_DENIED: "SCOPE_DENIED";
+    /** 404 — target absent (within the caller's tenant). */
+    readonly NOT_FOUND: "NOT_FOUND";
+    /** 409 — duplicate key or cross-tenant violation. */
+    readonly CONFLICT: "CONFLICT";
+    /** 423 — account is locked (Doc 03 §8). */
+    readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
+    /** 429 — throttled. */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /**
+     * 500 — the request failed for a reason the server did not anticipate.
+     *
+     * The one code a caller can never act on, and the one every caller must be
+     * able to parse: without it, an unhandled exception escapes as some other
+     * body shape and `isIamErrorResponse` rejects the server's own error. The
+     * `message` is always generic — an exception's text can carry a query, a
+     * connection string, or a row — and `requestId` is what correlates it with
+     * the logged stack (Doc 06 §2, added Session 6).
+     */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+export type IamErrorCode = (typeof IamErrorCode)[keyof typeof IamErrorCode];
+/** Every code, in Doc 06 §2 table order. */
+export declare const IAM_ERROR_CODES: readonly ["VALIDATION_FAILED", "AUTH_REQUIRED", "INVALID_CREDENTIALS", "PERMISSION_DENIED", "SCOPE_DENIED", "NOT_FOUND", "CONFLICT", "ACCOUNT_LOCKED", "RATE_LIMITED", "INTERNAL_ERROR"];
+/** code → HTTP status, per the Doc 06 §2 table. */
+export declare const IAM_ERROR_HTTP_STATUS: Readonly<Record<IamErrorCode, number>>;
+/** One field-level complaint accompanying `VALIDATION_FAILED`. */
+export interface IamErrorDetail {
+    field: string;
+    message: string;
+}
+export interface IamError {
+    code: IamErrorCode;
+    /**
+     * Human-readable message. Denials must stay non-committal: a 403 never
+     * reveals whether the target exists in another tenant (Doc 06 §2).
+     */
+    message: string;
+    /** Correlates the response with server logs and audit records. */
+    requestId: string;
+    details?: IamErrorDetail[];
+}
+/** The single response shape for every error the IAM returns (Doc 06 §2). */
+export interface IamErrorResponse {
+    error: IamError;
+}
+export declare function isIamErrorCode(value: unknown): value is IamErrorCode;
+export declare function isIamErrorResponse(value: unknown): value is IamErrorResponse;
+/** HTTP status for a code — the mapping consumers and the filter share. */
+export declare function httpStatusForIamError(code: IamErrorCode): number;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,YAAY;IACvB,+EAA+E;;IAE/E,+CAA+C;;IAE/C,8EAA8E;;IAE9E,2DAA2D;;IAE3D,0EAA0E;;IAE1E,wDAAwD;;IAExD,qDAAqD;;IAErD,2CAA2C;;IAE3C,uBAAuB;;IAEvB;;;;;;;;;OASG;;CAEK,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E,4CAA4C;AAC5C,eAAO,MAAM,eAAe,0LAWgB,CAAC;AAE7C,mDAAmD;AACnD,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAYrE,CAAC;AAEL,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAKpE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAY5E;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEhE"}

package/dist/errors.js

@@ -0,0 +1,83 @@
+/**
+ * Error contract — the envelope and the code table from Doc 06 §2.
+ *
+ * The table there is authoritative and closed: adding a code is a spec change,
+ * not an implementation detail, because consumers (`iam-client`, admin-web,
+ * every future module) branch on these values.
+ */
+export const IamErrorCode = {
+    /** 400 — request failed validation; see `details` for the offending fields. */
+    VALIDATION_FAILED: 'VALIDATION_FAILED',
+    /** 401 — no (or unverifiable) bearer token. */
+    AUTH_REQUIRED: 'AUTH_REQUIRED',
+    /** 401 — login rejected. Generic by design: never hints at user existence. */
+    INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+    /** 403 — subject does not hold the required permission. */
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    /** 403 — permission held, but not at a scope node covering the target. */
+    SCOPE_DENIED: 'SCOPE_DENIED',
+    /** 404 — target absent (within the caller's tenant). */
+    NOT_FOUND: 'NOT_FOUND',
+    /** 409 — duplicate key or cross-tenant violation. */
+    CONFLICT: 'CONFLICT',
+    /** 423 — account is locked (Doc 03 §8). */
+    ACCOUNT_LOCKED: 'ACCOUNT_LOCKED',
+    /** 429 — throttled. */
+    RATE_LIMITED: 'RATE_LIMITED',
+    /**
+     * 500 — the request failed for a reason the server did not anticipate.
+     *
+     * The one code a caller can never act on, and the one every caller must be
+     * able to parse: without it, an unhandled exception escapes as some other
+     * body shape and `isIamErrorResponse` rejects the server's own error. The
+     * `message` is always generic — an exception's text can carry a query, a
+     * connection string, or a row — and `requestId` is what correlates it with
+     * the logged stack (Doc 06 §2, added Session 6).
+     */
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+};
+/** Every code, in Doc 06 §2 table order. */
+export const IAM_ERROR_CODES = [
+    IamErrorCode.VALIDATION_FAILED,
+    IamErrorCode.AUTH_REQUIRED,
+    IamErrorCode.INVALID_CREDENTIALS,
+    IamErrorCode.PERMISSION_DENIED,
+    IamErrorCode.SCOPE_DENIED,
+    IamErrorCode.NOT_FOUND,
+    IamErrorCode.CONFLICT,
+    IamErrorCode.ACCOUNT_LOCKED,
+    IamErrorCode.RATE_LIMITED,
+    IamErrorCode.INTERNAL_ERROR,
+];
+/** code → HTTP status, per the Doc 06 §2 table. */
+export const IAM_ERROR_HTTP_STATUS = Object.freeze({
+    [IamErrorCode.VALIDATION_FAILED]: 400,
+    [IamErrorCode.AUTH_REQUIRED]: 401,
+    [IamErrorCode.INVALID_CREDENTIALS]: 401,
+    [IamErrorCode.PERMISSION_DENIED]: 403,
+    [IamErrorCode.SCOPE_DENIED]: 403,
+    [IamErrorCode.NOT_FOUND]: 404,
+    [IamErrorCode.CONFLICT]: 409,
+    [IamErrorCode.ACCOUNT_LOCKED]: 423,
+    [IamErrorCode.RATE_LIMITED]: 429,
+    [IamErrorCode.INTERNAL_ERROR]: 500,
+});
+export function isIamErrorCode(value) {
+    return (typeof value === 'string' &&
+        IAM_ERROR_CODES.includes(value));
+}
+export function isIamErrorResponse(value) {
+    if (typeof value !== 'object' || value === null || !('error' in value)) {
+        return false;
+    }
+    const { error } = value;
+    return (typeof error === 'object' &&
+        error !== null &&
+        isIamErrorCode(error.code) &&
+        typeof error.message === 'string' &&
+        typeof error.requestId === 'string');
+}
+/** HTTP status for a code — the mapping consumers and the filter share. */
+export function httpStatusForIamError(code) {
+    return IAM_ERROR_HTTP_STATUS[code];
+}

package/dist/grants.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Authorization contract — the resolved WHO × WHAT × WHERE answer every module
+ * consumes (Doc 04 §4–6).
+ */
+import { SubjectType } from './jwt.js';
+/**
+ * A namespaced permission key, `app.resource.action` (Doc 01 §3.2).
+ *
+ * Deliberately a plain `string`: permission keys are **data**, created at
+ * runtime through the registry. The IAM must never enumerate them in code
+ * (Doc 02 §8) — a union type here would be exactly that.
+ */
+export type PermissionKey = string;
+/**
+ * A materialized `ltree` path identifying a scope-tree node,
+ * `n_<hex>.n_<hex>.…` (Doc 01 §3.5). Coverage is the prefix test `<@`.
+ */
+export type ScopePath = string;
+/**
+ * A subject's complete grant set (Doc 04 §4.1).
+ *
+ * `scopes[permKey]` is the **minimal covering set** of paths for that
+ * permission: if an ancestor path is present, its descendants are dropped
+ * because `<@` already covers them. Consumers may rely on that minimization.
+ */
+export interface ResolvedGrants {
+    /** Flat list of held permission keys, for quick "has permission" checks. */
+    permissions: PermissionKey[];
+    /** permission key → minimal set of covering scope paths. */
+    scopes: Record<PermissionKey, ScopePath[]>;
+}
+/**
+ * The cached form of {@link ResolvedGrants} (Doc 04 §6). `v` is the
+ * `(client, subject)` version counter; a mismatch against the authoritative
+ * counter is treated as a cache miss, which is how role-level changes
+ * invalidate without enumerating subjects (Doc 04 §7).
+ */
+export interface CachedGrants extends ResolvedGrants {
+    v: number;
+}
+/** `POST /iam/permissions/check` body (Doc 06 §11). */
+export interface PermissionCheckRequest {
+    permission: PermissionKey;
+    scopeNodeId: string;
+}
+export interface PermissionCheckResponse {
+    allowed: boolean;
+}
+/** Optional narrowing of `/iam/permissions/resolve` to one application's slice. */
+export interface ResolveQuery {
+    applicationId?: string;
+}
+/**
+ * Payload of the `perms.invalidated` event (Doc 04 §7). Either a specific
+ * subject or a role whose bound subjects are affected.
+ */
+export interface PermsInvalidatedEvent {
+    clientId: string;
+    subjectId?: string;
+    subjectType?: SubjectType;
+    roleId?: string;
+}
+/** Redis key prefix for cached grants (Doc 04 §6). */
+export declare 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 declare function grantsCacheKey(clientId: string, subjectType: SubjectType, subjectId: string): string;
+//# sourceMappingURL=grants.d.ts.map

package/dist/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../src/grants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,CAAC,EAAE,MAAM,CAAC;CACX;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,aAAa,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER"}