@plantops/iam-client 0.1.0

package/README.md

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

package/dist/auth.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The token lifecycle: where credentials are kept, and when they are renewed.
+ *
+ * Separated from the `/auth/*` endpoint methods in `endpoints/auth.ts` on
+ * purpose. Those are HTTP; this is state — and it is the state two very
+ * different consumers need to control. A future operational module holds one
+ * service-account token in memory for the process's lifetime; `admin-web` holds
+ * a human's pair somewhere that survives a page reload, and would rather that
+ * somewhere were its own decision than this library's (Doc 09 §1). So the store
+ * is a two-method port, {@link MemoryTokenStore} is the default, and nothing
+ * here ever names `localStorage`, a cookie, or a file.
+ *
+ * ## Single-flight refresh
+ *
+ * The property that matters, and the reason this is a class rather than a
+ * closure over a variable. A screen that loads six panels issues six requests
+ * with the same expired access token and gets six `401`s within a few
+ * milliseconds of each other. Six refreshes would follow — and because
+ * `POST /auth/refresh` **rotates** (Doc 03 §4), five of them would present a
+ * token the first has already consumed, which the server is right to treat as
+ * replay. One in-flight refresh is therefore not an optimisation but a
+ * correctness requirement: {@link TokenSession.refresh} hands every concurrent
+ * caller the same promise, and the reuse-detection grace window of Doc 03 §4.1
+ * covers only what this cannot.
+ */
+import type { AccessTokenResponse, TokenPairResponse } from '@plantops/contracts';
+/** What a store holds. Access token, its renewal, and when it lapses. */
+export interface StoredTokens {
+    accessToken: string;
+    /** `null` for a service account: `POST /auth/token` issues no refresh token. */
+    refreshToken: string | null;
+    /**
+     * Epoch milliseconds, derived from `expires_in` when the pair was issued, or
+     * `null` when the tokens were adopted from elsewhere without one. `null`
+     * disables proactive renewal — the token is then used until a `401` says
+     * otherwise, which is correct, just one round trip slower.
+     */
+    expiresAt: number | null;
+}
+/**
+ * Where tokens live between calls.
+ *
+ * Both methods may be async so that a store can be a keychain, an encrypted
+ * file, or an `IndexedDB` handle. `write(null)` clears.
+ */
+export interface TokenStore {
+    read(): StoredTokens | null | Promise<StoredTokens | null>;
+    write(tokens: StoredTokens | null): void | Promise<void>;
+}
+/** The default: tokens last as long as the client object does. */
+export declare class MemoryTokenStore implements TokenStore {
+    private tokens;
+    read(): StoredTokens | null;
+    write(tokens: StoredTokens | null): void;
+}
+/** Why {@link TokenSessionOptions.onSessionEnded} fired. */
+export type SessionEndReason = 'logout' | 'refresh_failed';
+export interface TokenSessionOptions {
+    store?: TokenStore;
+    /** Injectable clock, so the expiry tests need no timers. */
+    now?: () => number;
+    /**
+     * Renew this many seconds before the access token actually lapses.
+     *
+     * Zero would mean every renewal costs a wasted round trip — the request that
+     * discovers the `401`. Thirty seconds is comfortably more than a slow request
+     * plus the 60-second clock skew the server already tolerates
+     * (`CLOCK_SKEW_LEEWAY_SECONDS`), and comfortably less than the 900-second
+     * access-token lifetime, so it neither renews constantly nor cuts it fine.
+     */
+    refreshLeewaySeconds?: number;
+    /**
+     * Fired when the session is over: the caller logged out, or a refresh failed
+     * and the stored tokens were dropped. `admin-web` sends the user to the login
+     * screen from here (Doc 09 §1).
+     */
+    onSessionEnded?: (reason: SessionEndReason) => void;
+}
+export declare class TokenSession {
+    /** `POST /auth/refresh`, injected because it goes back through the transport. */
+    private readonly exchangeRefreshToken;
+    private readonly store;
+    private readonly now;
+    private readonly leewayMs;
+    private readonly onSessionEnded;
+    /** The one in-flight refresh every concurrent caller shares. */
+    private pending;
+    constructor(
+    /** `POST /auth/refresh`, injected because it goes back through the transport. */
+    exchangeRefreshToken: (refreshToken: string) => Promise<TokenPairResponse>, options?: TokenSessionOptions);
+    /** What is stored right now, without renewing anything. */
+    tokens(): Promise<StoredTokens | null>;
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * The token to send, renewed first if it is about to lapse.
+     *
+     * A failed proactive renewal answers `null` rather than the token it could
+     * not replace: the stored pair is gone by then, and sending a token this
+     * object no longer holds would produce a `401` whose retry has nothing left
+     * to refresh with.
+     */
+    accessToken(): Promise<string | null>;
+    /**
+     * The transport's `401` hook.
+     *
+     * Two things happen here that a plain "refresh on 401" would get wrong. The
+     * first is the check that the stored token is still the one that failed: when
+     * six requests race, five of them arrive after the refresh has already landed
+     * and simply need retrying with what is now stored — no second refresh, and
+     * no rotation of a token nobody has used yet. The second is that failure is
+     * `false`, not an exception: the caller's original `401` is the honest answer
+     * to their request, and replacing it with a refresh error would report the
+     * wrong failed call.
+     */
+    reauthorize(usedToken: string | null): Promise<boolean>;
+    /**
+     * Renews the pair, sharing one exchange with every concurrent caller.
+     *
+     * A failed refresh clears the store: the refresh token is either expired,
+     * revoked, or has been replayed, and all three mean this session is over
+     * (Doc 03 §4.1). Keeping it would guarantee that every later call spends a
+     * round trip rediscovering the same thing.
+     */
+    refresh(): Promise<TokenPairResponse>;
+    private runRefresh;
+    /** Takes the tokens a login, refresh or service-token exchange returned. */
+    adopt(tokens: TokenPairResponse | AccessTokenResponse): Promise<void>;
+    /** Adopts tokens from somewhere else — a server-rendered page, another tab. */
+    restore(tokens: StoredTokens | null): Promise<void>;
+    /** Drops the tokens locally. The server-side revocation is `POST /auth/logout`. */
+    clear(): Promise<void>;
+    private forget;
+    private expiringSoon;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAElF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,IAAI,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC3D,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,kEAAkE;AAClE,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,MAAM,CAA6B;IAE3C,IAAI,IAAI,YAAY,GAAG,IAAI;IAI3B,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;CAGzC;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACrD;AAID,qBAAa,YAAY;IAYrB,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAZvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAEjB;IAEd,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAA2C;;IAGxD,iFAAiF;IAChE,oBAAoB,EAAE,CACrC,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC,iBAAiB,CAAC,EAC/B,OAAO,GAAE,mBAAwB;IASnC,2DAA2D;IACrD,MAAM,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzC;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAe3C;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAc7D;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;YAS7B,UAAU;IAgBxB,4EAA4E;IACtE,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3E,+EAA+E;IACzE,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,mFAAmF;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,MAAM;IAKpB,OAAO,CAAC,YAAY;CAGrB"}

package/dist/auth.js

@@ -0,0 +1,168 @@
+/**
+ * The token lifecycle: where credentials are kept, and when they are renewed.
+ *
+ * Separated from the `/auth/*` endpoint methods in `endpoints/auth.ts` on
+ * purpose. Those are HTTP; this is state — and it is the state two very
+ * different consumers need to control. A future operational module holds one
+ * service-account token in memory for the process's lifetime; `admin-web` holds
+ * a human's pair somewhere that survives a page reload, and would rather that
+ * somewhere were its own decision than this library's (Doc 09 §1). So the store
+ * is a two-method port, {@link MemoryTokenStore} is the default, and nothing
+ * here ever names `localStorage`, a cookie, or a file.
+ *
+ * ## Single-flight refresh
+ *
+ * The property that matters, and the reason this is a class rather than a
+ * closure over a variable. A screen that loads six panels issues six requests
+ * with the same expired access token and gets six `401`s within a few
+ * milliseconds of each other. Six refreshes would follow — and because
+ * `POST /auth/refresh` **rotates** (Doc 03 §4), five of them would present a
+ * token the first has already consumed, which the server is right to treat as
+ * replay. One in-flight refresh is therefore not an optimisation but a
+ * correctness requirement: {@link TokenSession.refresh} hands every concurrent
+ * caller the same promise, and the reuse-detection grace window of Doc 03 §4.1
+ * covers only what this cannot.
+ */
+/** The default: tokens last as long as the client object does. */
+export class MemoryTokenStore {
+    tokens = null;
+    read() {
+        return this.tokens;
+    }
+    write(tokens) {
+        this.tokens = tokens;
+    }
+}
+const DEFAULT_REFRESH_LEEWAY_SECONDS = 30;
+export class TokenSession {
+    exchangeRefreshToken;
+    store;
+    now;
+    leewayMs;
+    onSessionEnded;
+    /** The one in-flight refresh every concurrent caller shares. */
+    pending = null;
+    constructor(
+    /** `POST /auth/refresh`, injected because it goes back through the transport. */
+    exchangeRefreshToken, options = {}) {
+        this.exchangeRefreshToken = exchangeRefreshToken;
+        this.store = options.store ?? new MemoryTokenStore();
+        this.now = options.now ?? (() => Date.now());
+        this.leewayMs =
+            (options.refreshLeewaySeconds ?? DEFAULT_REFRESH_LEEWAY_SECONDS) * 1000;
+        this.onSessionEnded = options.onSessionEnded;
+    }
+    /** What is stored right now, without renewing anything. */
+    async tokens() {
+        return (await this.store.read()) ?? null;
+    }
+    async isAuthenticated() {
+        return (await this.tokens()) !== null;
+    }
+    /**
+     * The token to send, renewed first if it is about to lapse.
+     *
+     * A failed proactive renewal answers `null` rather than the token it could
+     * not replace: the stored pair is gone by then, and sending a token this
+     * object no longer holds would produce a `401` whose retry has nothing left
+     * to refresh with.
+     */
+    async accessToken() {
+        const current = await this.tokens();
+        if (current === null)
+            return null;
+        if (current.refreshToken !== null && this.expiringSoon(current)) {
+            try {
+                return (await this.refresh()).access_token;
+            }
+            catch {
+                return null;
+            }
+        }
+        return current.accessToken;
+    }
+    /**
+     * The transport's `401` hook.
+     *
+     * Two things happen here that a plain "refresh on 401" would get wrong. The
+     * first is the check that the stored token is still the one that failed: when
+     * six requests race, five of them arrive after the refresh has already landed
+     * and simply need retrying with what is now stored — no second refresh, and
+     * no rotation of a token nobody has used yet. The second is that failure is
+     * `false`, not an exception: the caller's original `401` is the honest answer
+     * to their request, and replacing it with a refresh error would report the
+     * wrong failed call.
+     */
+    async reauthorize(usedToken) {
+        const current = await this.tokens();
+        if (current === null)
+            return false;
+        if (usedToken !== null && current.accessToken !== usedToken)
+            return true;
+        if (current.refreshToken === null)
+            return false;
+        try {
+            await this.refresh();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Renews the pair, sharing one exchange with every concurrent caller.
+     *
+     * A failed refresh clears the store: the refresh token is either expired,
+     * revoked, or has been replayed, and all three mean this session is over
+     * (Doc 03 §4.1). Keeping it would guarantee that every later call spends a
+     * round trip rediscovering the same thing.
+     */
+    async refresh() {
+        if (this.pending !== null)
+            return this.pending;
+        this.pending = this.runRefresh().finally(() => {
+            this.pending = null;
+        });
+        return this.pending;
+    }
+    async runRefresh() {
+        const current = await this.tokens();
+        if (current === null || current.refreshToken === null) {
+            throw new Error('No refresh token: nothing to renew.');
+        }
+        try {
+            const pair = await this.exchangeRefreshToken(current.refreshToken);
+            await this.adopt(pair);
+            return pair;
+        }
+        catch (error) {
+            await this.forget('refresh_failed');
+            throw error;
+        }
+    }
+    /** Takes the tokens a login, refresh or service-token exchange returned. */
+    async adopt(tokens) {
+        await this.store.write({
+            accessToken: tokens.access_token,
+            refreshToken: 'refresh_token' in tokens ? tokens.refresh_token : null,
+            expiresAt: typeof tokens.expires_in === 'number'
+                ? this.now() + tokens.expires_in * 1000
+                : null,
+        });
+    }
+    /** Adopts tokens from somewhere else — a server-rendered page, another tab. */
+    async restore(tokens) {
+        await this.store.write(tokens);
+    }
+    /** Drops the tokens locally. The server-side revocation is `POST /auth/logout`. */
+    async clear() {
+        await this.forget('logout');
+    }
+    async forget(reason) {
+        await this.store.write(null);
+        this.onSessionEnded?.(reason);
+    }
+    expiringSoon(tokens) {
+        return tokens.expiresAt !== null && tokens.expiresAt - this.leewayMs <= this.now();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `IamClient` — one import gives a consumer authenticated, typed IAM access
+ * (Doc 08 §2).
+ *
+ * The composition root, and deliberately the only file that knows all the parts
+ * exist: the transport, the token lifecycle, the grants cache and the ten
+ * endpoint modules. Everything it wires together is separately constructible, so
+ * a consumer with an unusual need — a script that only talks to the registry, a
+ * test that wants the cache without a socket — is never forced through this
+ * class.
+ *
+ * ## What it is responsible for that nothing else is
+ *
+ * Three couplings live here because they exist only when the parts are
+ * assembled:
+ *
+ * 1. The transport asks {@link TokenSession} for a token, and hands it back on a
+ *    `401` — which is what makes the automatic, single-flight refresh work
+ *    without any endpoint module knowing about tokens.
+ * 2. The refresh call itself goes back out through the transport, so it gets the
+ *    same base URL, headers, timeout and error mapping as everything else.
+ * 3. Any change of identity — login, service-token exchange, logout, refresh —
+ *    empties the grants cache. Serving one subject's grants to the next is the
+ *    one caching mistake that would hand a user somebody else's menu.
+ *
+ * ## Every Doc 06 surface has a typed method
+ *
+ * `/iam/audit` was the one gap while Session 25's endpoint and its contract
+ * types did not exist — a method here would have had to invent both, and that
+ * session would then have been implementing against a client rather than against
+ * Doc 06. Both landed, and `endpoints/audit.ts` closed it in Session 37.
+ */
+import type { ResolvedGrants, ResolveQuery } from '@plantops/contracts';
+import { TokenSession, type SessionEndReason, type TokenStore, type TokenSessionOptions } from './auth.js';
+import { type ApplicationsApi, type AuditApi, type EntitlementsApi, type AuthApi, type ClientsApi, type NavigationApi, type PermissionsApi, type RoleBindingsApi, type RolesApi, type ScopesApi, type ServiceAccountsApi, type UsersApi } from './endpoints/index.js';
+import { type FetchLike, type Requester } from './http.js';
+export interface IamClientOptions {
+    /** The API root — the origin, without the `/iam` or `/auth` prefix. */
+    baseUrl: string;
+    /** Defaults to the runtime's global. Supply one to test, or to instrument. */
+    fetch?: FetchLike;
+    /** Sent on every request — a correlation header, a user agent. */
+    headers?: Readonly<Record<string, string>>;
+    /** Abort a request that has taken this long. Omit for no client-side limit. */
+    timeoutMs?: number;
+    /** Where tokens live. Defaults to memory; a browser supplies its own. */
+    tokenStore?: TokenStore;
+    /** Renew this many seconds before the access token lapses. Default 30. */
+    refreshLeewaySeconds?: TokenSessionOptions['refreshLeewaySeconds'];
+    /** How long {@link IamClient.grants} may serve a cached answer. Default 60. */
+    resolveCacheTtlSeconds?: number;
+    /** Injectable clock, shared by the token expiry and the cache. */
+    now?: () => number;
+    /** The session ended: the caller logged out, or a refresh was refused. */
+    onSessionEnded?: (reason: SessionEndReason) => void;
+}
+export declare class IamClient {
+    /** The token lifecycle: read, restore or clear credentials directly. */
+    readonly session: TokenSession;
+    readonly auth: AuthApi;
+    readonly applications: ApplicationsApi;
+    readonly clients: ClientsApi;
+    readonly scopes: ScopesApi;
+    readonly roles: RolesApi;
+    readonly users: UsersApi;
+    readonly roleBindings: RoleBindingsApi;
+    readonly serviceAccounts: ServiceAccountsApi;
+    readonly permissions: PermissionsApi;
+    readonly navigation: NavigationApi;
+    readonly audit: AuditApi;
+    /**
+     * Term, ceilings and per-application entitlement.
+     *
+     * Deliberately not folded into {@link IamClient.grants}: grants invalidate on
+     * a version counter, entitlements go stale on a clock, and one cache cannot
+     * serve both. See `endpoints/entitlements.ts`.
+     */
+    readonly entitlements: EntitlementsApi;
+    /**
+     * The raw, authenticated request function.
+     *
+     * The escape hatch for an endpoint this library does not yet type. Nothing on
+     * Doc 06's surface needs it today; it stays because the alternative, when the
+     * next route arrives ahead of its method, is a consumer abandoning the token
+     * handling and error mapping for all of them.
+     */
+    readonly request: Requester;
+    private readonly grantsCache;
+    constructor(options: IamClientOptions);
+    /**
+     * The bearer's grants, cached (Doc 06 §11).
+     *
+     * What a module's `PermissionGuard` should call on every gated request: the
+     * burst of authorizations one request fan-out produces collapses into a single
+     * resolve, and the answer is reused for the cache's lifetime.
+     */
+    grants(query?: ResolveQuery): Promise<ResolvedGrants>;
+    /** Re-resolves now, ignoring the cache — after a change the caller just made. */
+    refreshGrants(query?: ResolveQuery): Promise<ResolvedGrants>;
+    /**
+     * Drops cached grants — for one application, or all of them.
+     *
+     * The hook a consumer subscribed to `perms.invalidated` (Doc 04 §7) calls, and
+     * the reason such a consumer may safely raise `resolveCacheTtlSeconds`.
+     */
+    invalidateGrants(applicationId?: string): void;
+}
+/** `createIamClient({ baseUrl })` — the same thing, for consumers that prefer it. */
+export declare function createIamClient(options: IamClientOptions): IamClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AAG3F,OAAO,EACL,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EAaL,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAG1E,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;IACnE,+EAA+E;IAC/E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACrD;AAED,qBAAa,SAAS;IACpB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAE/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IAEvC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAE5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;gBAE/B,OAAO,EAAE,gBAAgB;IAgDrC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,GAAE,YAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIzD,iFAAiF;IACjF,aAAa,CAAC,KAAK,GAAE,YAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIhE;;;;;OAKG;IACH,gBAAgB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;CAG/C;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAEpE"}

package/dist/client.js

@@ -0,0 +1,135 @@
+/**
+ * `IamClient` — one import gives a consumer authenticated, typed IAM access
+ * (Doc 08 §2).
+ *
+ * The composition root, and deliberately the only file that knows all the parts
+ * exist: the transport, the token lifecycle, the grants cache and the ten
+ * endpoint modules. Everything it wires together is separately constructible, so
+ * a consumer with an unusual need — a script that only talks to the registry, a
+ * test that wants the cache without a socket — is never forced through this
+ * class.
+ *
+ * ## What it is responsible for that nothing else is
+ *
+ * Three couplings live here because they exist only when the parts are
+ * assembled:
+ *
+ * 1. The transport asks {@link TokenSession} for a token, and hands it back on a
+ *    `401` — which is what makes the automatic, single-flight refresh work
+ *    without any endpoint module knowing about tokens.
+ * 2. The refresh call itself goes back out through the transport, so it gets the
+ *    same base URL, headers, timeout and error mapping as everything else.
+ * 3. Any change of identity — login, service-token exchange, logout, refresh —
+ *    empties the grants cache. Serving one subject's grants to the next is the
+ *    one caching mistake that would hand a user somebody else's menu.
+ *
+ * ## Every Doc 06 surface has a typed method
+ *
+ * `/iam/audit` was the one gap while Session 25's endpoint and its contract
+ * types did not exist — a method here would have had to invent both, and that
+ * session would then have been implementing against a client rather than against
+ * Doc 06. Both landed, and `endpoints/audit.ts` closed it in Session 37.
+ */
+import { AUTH_ROUTE_PREFIX } from '@plantops/contracts';
+import { TokenSession, } from './auth.js';
+import { applicationsEndpoints, auditEndpoints, entitlementsEndpoints, authEndpoints, clientsEndpoints, navigationEndpoints, permissionsEndpoints, roleBindingsEndpoints, rolesEndpoints, scopesEndpoints, serviceAccountsEndpoints, usersEndpoints, } from './endpoints/index.js';
+import { HttpTransport } from './http.js';
+import { ResolveCache } from './resolve-cache.js';
+export class IamClient {
+    /** The token lifecycle: read, restore or clear credentials directly. */
+    session;
+    auth;
+    applications;
+    clients;
+    scopes;
+    roles;
+    users;
+    roleBindings;
+    serviceAccounts;
+    permissions;
+    navigation;
+    audit;
+    /**
+     * Term, ceilings and per-application entitlement.
+     *
+     * Deliberately not folded into {@link IamClient.grants}: grants invalidate on
+     * a version counter, entitlements go stale on a clock, and one cache cannot
+     * serve both. See `endpoints/entitlements.ts`.
+     */
+    entitlements;
+    /**
+     * The raw, authenticated request function.
+     *
+     * The escape hatch for an endpoint this library does not yet type. Nothing on
+     * Doc 06's surface needs it today; it stays because the alternative, when the
+     * next route arrives ahead of its method, is a consumer abandoning the token
+     * handling and error mapping for all of them.
+     */
+    request;
+    grantsCache;
+    constructor(options) {
+        const transport = new HttpTransport({
+            baseUrl: options.baseUrl,
+            fetch: options.fetch,
+            headers: options.headers,
+            timeoutMs: options.timeoutMs,
+            authorize: () => this.session.accessToken(),
+            reauthorize: (usedToken) => this.session.reauthorize(usedToken),
+        });
+        this.request = transport.request;
+        this.session = new TokenSession((refreshToken) => this.request({
+            method: 'POST',
+            path: `${AUTH_ROUTE_PREFIX}/refresh`,
+            body: { refresh_token: refreshToken },
+            auth: 'none',
+        }), {
+            store: options.tokenStore,
+            now: options.now,
+            refreshLeewaySeconds: options.refreshLeewaySeconds,
+            onSessionEnded: options.onSessionEnded,
+        });
+        this.permissions = permissionsEndpoints(this.request);
+        this.grantsCache = new ResolveCache((query) => this.permissions.resolve(query), {
+            ttlSeconds: options.resolveCacheTtlSeconds,
+            now: options.now,
+        });
+        this.auth = authEndpoints(this.request, this.session, () => this.grantsCache.clear());
+        this.applications = applicationsEndpoints(this.request);
+        this.clients = clientsEndpoints(this.request);
+        this.scopes = scopesEndpoints(this.request);
+        this.roles = rolesEndpoints(this.request);
+        this.users = usersEndpoints(this.request);
+        this.roleBindings = roleBindingsEndpoints(this.request);
+        this.serviceAccounts = serviceAccountsEndpoints(this.request);
+        this.navigation = navigationEndpoints(this.request);
+        this.audit = auditEndpoints(this.request);
+        this.entitlements = entitlementsEndpoints(this.request);
+    }
+    /**
+     * The bearer's grants, cached (Doc 06 §11).
+     *
+     * What a module's `PermissionGuard` should call on every gated request: the
+     * burst of authorizations one request fan-out produces collapses into a single
+     * resolve, and the answer is reused for the cache's lifetime.
+     */
+    grants(query = {}) {
+        return this.grantsCache.get(query);
+    }
+    /** Re-resolves now, ignoring the cache — after a change the caller just made. */
+    refreshGrants(query = {}) {
+        return this.grantsCache.reload(query);
+    }
+    /**
+     * Drops cached grants — for one application, or all of them.
+     *
+     * The hook a consumer subscribed to `perms.invalidated` (Doc 04 §7) calls, and
+     * the reason such a consumer may safely raise `resolveCacheTtlSeconds`.
+     */
+    invalidateGrants(applicationId) {
+        this.grantsCache.invalidate(applicationId);
+    }
+}
+/** `createIamClient({ baseUrl })` — the same thing, for consumers that prefer it. */
+export function createIamClient(options) {
+    return new IamClient(options);
+}

package/dist/endpoints/applications.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `/iam/applications/*` — the platform application registry, Doc 06 §4.
+ *
+ * The four catalog routes and the manifest that replaces them are all here
+ * because they are one screen's worth of API (Doc 09 §2): an application, its
+ * permissions, its nav nodes, and the mapping between the last two.
+ */
+import type { ApplicationDTO, ApplicationManifest, CreateApplicationRequest, CreateNavNodesRequest, CreatePermissionsRequest, ManifestUpsertResponse, NavCatalogResponse, NavNodeCatalogDTO, NavPermissionsRequest, NavPermissionsResult, Paginated, PaginationQuery, PermissionDTO, UpdateApplicationRequest } from '@plantops/contracts';
+import type { Requester } from '../http.js';
+export interface ApplicationsApi {
+    create(body: CreateApplicationRequest): Promise<ApplicationDTO>;
+    list(query?: PaginationQuery): Promise<Paginated<ApplicationDTO>>;
+    /** Update, or the global on/off switch of Doc 02 §7. */
+    update(id: string, body: UpdateApplicationRequest): Promise<ApplicationDTO>;
+    addPermissions(id: string, body: CreatePermissionsRequest): Promise<PermissionDTO[]>;
+    listPermissions(id: string, query?: PaginationQuery): Promise<Paginated<PermissionDTO>>;
+    addNavNodes(id: string, body: CreateNavNodesRequest): Promise<NavNodeCatalogDTO[]>;
+    navTree(id: string): Promise<NavCatalogResponse>;
+    mapNavPermissions(id: string, body: NavPermissionsRequest): Promise<NavPermissionsResult>;
+    /**
+     * Removes mappings. Doc 06 §4's table stops at the POST; the DELETE exists
+     * because a mapping added by mistake has to be removable without a manifest
+     * upload (see `registry/nav.service.ts`).
+     */
+    unmapNavPermissions(id: string, body: NavPermissionsRequest): Promise<NavPermissionsResult>;
+    /**
+     * Idempotent upsert of the whole catalog from an application's manifest
+     * (Doc 02 §2). The body is the manifest document itself, unwrapped, so the
+     * file on disk and the body on the wire are the same thing.
+     */
+    upsertManifest(id: string, manifest: ApplicationManifest): Promise<ManifestUpsertResponse>;
+    /**
+     * What {@link ApplicationsApi.upsertManifest} *would* do — `?dryRun=true`.
+     *
+     * The preview behind Doc 09 §2.1's upload screen: the same validation, the
+     * same refusals and the same `ManifestDiff`, computed against the catalog as
+     * it stands and applied to nothing. `dry_run` comes back `true`, and `changed`
+     * answers whether confirming would do anything at all.
+     *
+     * A separate method rather than an options argument, because the difference
+     * between the two calls is whether they write. A boolean parameter that
+     * decides that reads the same at both call sites and is the wrong thing to get
+     * backwards.
+     */
+    previewManifest(id: string, manifest: ApplicationManifest): Promise<ManifestUpsertResponse>;
+}
+export declare function applicationsEndpoints(request: Requester): ApplicationsApi;
+//# sourceMappingURL=applications.d.ts.map

package/dist/endpoints/applications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applications.d.ts","sourceRoot":"","sources":["../../src/endpoints/applications.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAClE,wDAAwD;IACxD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE5E,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACrF,eAAe,CACb,EAAE,EAAE,MAAM,EACV,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;IAErC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACnF,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjD,iBAAiB,CACf,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC;;;;OAIG;IACH,mBAAmB,CACjB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC;;;;OAIG;IACH,cAAc,CACZ,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEnC;;;;;;;;;;;;OAYG;IACH,eAAe,CACb,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACpC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,GAAG,eAAe,CAiCzE"}

package/dist/endpoints/applications.js

@@ -0,0 +1,30 @@
+/**
+ * `/iam/applications/*` — the platform application registry, Doc 06 §4.
+ *
+ * The four catalog routes and the manifest that replaces them are all here
+ * because they are one screen's worth of API (Doc 09 §2): an application, its
+ * permissions, its nav nodes, and the mapping between the last two.
+ */
+import { IAM_ROUTE_PREFIX } from '@plantops/contracts';
+export function applicationsEndpoints(request) {
+    const base = `${IAM_ROUTE_PREFIX}/applications`;
+    const at = (id, suffix = '') => `${base}/${encodeURIComponent(id)}${suffix}`;
+    return {
+        create: (body) => request({ method: 'POST', path: base, body }),
+        list: (query) => request({ method: 'GET', path: base, query: { ...query } }),
+        update: (id, body) => request({ method: 'PATCH', path: at(id), body }),
+        addPermissions: (id, body) => request({ method: 'POST', path: at(id, '/permissions'), body }),
+        listPermissions: (id, query) => request({ method: 'GET', path: at(id, '/permissions'), query: { ...query } }),
+        addNavNodes: (id, body) => request({ method: 'POST', path: at(id, '/nav'), body }),
+        navTree: (id) => request({ method: 'GET', path: at(id, '/nav') }),
+        mapNavPermissions: (id, body) => request({ method: 'POST', path: at(id, '/nav-permissions'), body }),
+        unmapNavPermissions: (id, body) => request({ method: 'DELETE', path: at(id, '/nav-permissions'), body }),
+        upsertManifest: (id, manifest) => request({ method: 'POST', path: at(id, '/manifest'), body: manifest }),
+        previewManifest: (id, manifest) => request({
+            method: 'POST',
+            path: at(id, '/manifest'),
+            query: { dryRun: true },
+            body: manifest,
+        }),
+    };
+}