@camstack/system 1.2.390 → 1.2.392

package/dist/auth/auth-manager.d.ts

@@ -1,140 +1,141 @@
-import { IScopedLogger, TokenPayload, SsoBridgeClaimsSchema } from '@camstack/types';
-import { z } from 'zod';
-import { JwtSigningKeySource } from './jwt-signing-key.js';
+import type { IScopedLogger, TokenPayload } from "@camstack/types";
+import { SsoBridgeClaimsSchema } from "@camstack/types";
+import type { z } from "zod";
+import { type JwtSigningKeySource } from "./jwt-signing-key.js";
 export type { TokenPayload };
 export type AuthConfigReader = {
-    /**
-     * `undefined` is part of the contract, not an accident: a reader answers
-     * only the paths it can (`local-auth` pre-resolves a fixed set; a
-     * `ConfigManager` falls through to RUNTIME_DEFAULTS and then to nothing).
-     * Every consumer here must handle the absent case explicitly.
-     */
-    get<T>(path: string): T | undefined;
-    update(section: string, data: Record<string, unknown>): void;
+	/**
+	* `undefined` is part of the contract, not an accident: a reader answers
+	* only the paths it can (`local-auth` pre-resolves a fixed set; a
+	* `ConfigManager` falls through to RUNTIME_DEFAULTS and then to nothing).
+	* Every consumer here must handle the absent case explicitly.
+	*/
+	get<T>(path: string): T | undefined;
+	update(section: string, data: Record<string, unknown>): void;
 };
 export declare class AuthManager {
-    private readonly config;
-    private readonly signingKey;
-    private readonly logger;
-    /**
-     * Offending `auth.tokenExpiry` values already reported by this instance.
-     *
-     * `signToken` re-reads the setting on EVERY mint so an operator's change
-     * takes effect without a restart — which also means a bad value would log
-     * once per login and once per silent refresh from every viewer. The refusal
-     * must be visible, not repeated: the first mint after a bad save logs, the
-     * rest resolve silently to the same default until the value changes.
-     */
-    private readonly reportedInvalidExpiries;
-    /**
-     * @param signingKey where the session signing key comes from — the process
-     *   slot `local-auth` fills from the keychain (D797). Never config, never
-     *   env; read on every mint and verify, and it THROWS while unavailable.
-     */
-    constructor(config: AuthConfigReader, logger?: IScopedLogger, signingKey?: JwtSigningKeySource);
-    /** The current signing key; throws `JwtSigningKeyUnavailableError` while there is none. */
-    private get jwtSecret();
-    /**
-     * @param options.expiresInSec an explicit lifetime (a session's access
-     *   token): wins over `auth.tokenExpiry`, bounded to at least one minute.
-     */
-    signToken(payload: Omit<TokenPayload, 'iat' | 'exp'>, options?: {
-        readonly expiresInSec?: number;
-    }): string;
-    /**
-     * The operator's `auth.tokenExpiry`, or `undefined` → DEFAULT_TOKEN_EXPIRY.
-     *
-     * On the hub this reader is `ConfigService`, which answers the key from its
-     * boot-time mirror of the settings store and REFUSES while that mirror is
-     * unknown (pending or failed, D675). A login must not fail over it, so the
-     * refusal signs with the default — and says so once per reason, because a
-     * mint that silently ignored a saved lifetime is the defect this setting
-     * already had once.
-     */
-    private readConfiguredExpiry;
-    verifyToken(token: string): TokenPayload;
-    hashPassword(password: string): Promise<string>;
-    comparePassword(password: string, hash: string): Promise<boolean>;
-    /**
-     * Mint a short-lived HMAC-signed bridge token used by SSO-style auth
-     * providers (OIDC, SAML, …) to hand the post-callback
-     * claims to `/api/auth/sso/finish` without trusting unsigned query
-     * parameters. The endpoint verifies the token signature with the same
-     * `jwtSecret` and only then mints the user session JWT. This closes
-     * the privilege-escalation gap where any client could craft a
-     * `?isAdmin=1` link to `/sso/finish` and become admin.
-     *
-     * The payload carries `kind: 'sso-bridge'` so `verifySsoBridgeToken`
-     * can reject session tokens reused as bridge tokens (and vice versa).
-     * TTL defaults to 5 minutes — long enough to survive the IdP
-     * redirect bounce, short enough that a leaked URL stops being useful
-     * before the operator notices.
-     */
-    signSsoBridgeToken(payload: SsoBridgeClaims, ttlSec?: number | 'never'): string;
-    /**
-     * Verify + decode a bridge token minted by `signSsoBridgeToken`.
-     * Returns `null` for invalid signature, expired token, or wrong
-     * `kind` claim. Never throws — the consumer ( `/sso/finish`) treats
-     * `null` as 400 Bad Request.
-     */
-    verifySsoBridgeToken(token: string): SsoBridgeClaims | null;
-    /**
-     * Mint a TOTP challenge token bridging the two-step login flow:
-     *
-     *   1. POST /login → password OK + user has 2FA  →  returns
-     *      `{requiresTotp: true, challengeToken: '...'}` (this token).
-     *   2. POST /login/totp-verify → operator types 6-digit code →
-     *      server verifies challenge token + code → mints the real
-     *      session JWT.
-     *
-     * The token carries `kind: 'totp-challenge'` so it can't be confused
-     * with a regular session token, plus the `userId` + `username` +
-     * `isAdmin` claims that will end up in the final session if the code
-     * verifies. TTL defaults to 5 minutes — long enough to type the code,
-     * short enough that an abandoned login can't be picked up later.
-     */
-    signTotpChallengeToken(payload: TotpChallengeClaims, ttlSec?: number): string;
-    /**
-     * A short-lived proof that the signed-in user just re-entered their password
-     * or used a passkey. Sensitive self-service actions (linking a sign-in
-     * account, disabling 2FA, removing a passkey, minting an admin token)
-     * require one. `kind: 'reauth'` keeps it from ever being a bearer.
-     */
-    signReauthToken(claims: ReauthClaims, ttlSec?: number): string;
-    /** Decode a re-authentication proof, or `null` (forged, expired, another kind). */
-    verifyReauthToken(token: string): ReauthClaims | null;
-    /**
-     * Verify + decode a TOTP challenge token. Returns `null` for any
-     * failure (invalid signature, expired, wrong `kind`, missing
-     * claims). The caller MUST also verify the 6-digit code against
-     * `totpManager.verify(userId, code)` before minting the real
-     * session — this method validates the bridge transport only.
-     */
-    verifyTotpChallengeToken(token: string): TotpChallengeClaims | null;
+	private readonly config;
+	private readonly signingKey;
+	private readonly logger;
+	/**
+	* Offending `auth.tokenExpiry` values already reported by this instance.
+	*
+	* `signToken` re-reads the setting on EVERY mint so an operator's change
+	* takes effect without a restart — which also means a bad value would log
+	* once per login and once per silent refresh from every viewer. The refusal
+	* must be visible, not repeated: the first mint after a bad save logs, the
+	* rest resolve silently to the same default until the value changes.
+	*/
+	private readonly reportedInvalidExpiries;
+	/**
+	* @param signingKey where the session signing key comes from — the process
+	*   slot `local-auth` fills from the keychain (D797). Never config, never
+	*   env; read on every mint and verify, and it THROWS while unavailable.
+	*/
+	constructor(config: AuthConfigReader, logger?: IScopedLogger, signingKey?: JwtSigningKeySource);
+	/** The current signing key; throws `JwtSigningKeyUnavailableError` while there is none. */
+	private get jwtSecret();
+	/**
+	* @param options.expiresInSec an explicit lifetime (a session's access
+	*   token): wins over `auth.tokenExpiry`, bounded to at least one minute.
+	*/
+	signToken(payload: Omit<TokenPayload, "iat" | "exp">, options?: {
+		readonly expiresInSec?: number;
+	}): string;
+	/**
+	* The operator's `auth.tokenExpiry`, or `undefined` → DEFAULT_TOKEN_EXPIRY.
+	*
+	* On the hub this reader is `ConfigService`, which answers the key from its
+	* boot-time mirror of the settings store and REFUSES while that mirror is
+	* unknown (pending or failed, D675). A login must not fail over it, so the
+	* refusal signs with the default — and says so once per reason, because a
+	* mint that silently ignored a saved lifetime is the defect this setting
+	* already had once.
+	*/
+	private readConfiguredExpiry;
+	verifyToken(token: string): TokenPayload;
+	hashPassword(password: string): Promise<string>;
+	comparePassword(password: string, hash: string): Promise<boolean>;
+	/**
+	* Mint a short-lived HMAC-signed bridge token used by SSO-style auth
+	* providers (OIDC, SAML, …) to hand the post-callback
+	* claims to `/api/auth/sso/finish` without trusting unsigned query
+	* parameters. The endpoint verifies the token signature with the same
+	* `jwtSecret` and only then mints the user session JWT. This closes
+	* the privilege-escalation gap where any client could craft a
+	* `?isAdmin=1` link to `/sso/finish` and become admin.
+	*
+	* The payload carries `kind: 'sso-bridge'` so `verifySsoBridgeToken`
+	* can reject session tokens reused as bridge tokens (and vice versa).
+	* TTL defaults to 5 minutes — long enough to survive the IdP
+	* redirect bounce, short enough that a leaked URL stops being useful
+	* before the operator notices.
+	*/
+	signSsoBridgeToken(payload: SsoBridgeClaims, ttlSec?: number | "never"): string;
+	/**
+	* Verify + decode a bridge token minted by `signSsoBridgeToken`.
+	* Returns `null` for invalid signature, expired token, or wrong
+	* `kind` claim. Never throws — the consumer ( `/sso/finish`) treats
+	* `null` as 400 Bad Request.
+	*/
+	verifySsoBridgeToken(token: string): SsoBridgeClaims | null;
+	/**
+	* Mint a TOTP challenge token bridging the two-step login flow:
+	*
+	*   1. POST /login → password OK + user has 2FA  →  returns
+	*      `{requiresTotp: true, challengeToken: '...'}` (this token).
+	*   2. POST /login/totp-verify → operator types 6-digit code →
+	*      server verifies challenge token + code → mints the real
+	*      session JWT.
+	*
+	* The token carries `kind: 'totp-challenge'` so it can't be confused
+	* with a regular session token, plus the `userId` + `username` +
+	* `isAdmin` claims that will end up in the final session if the code
+	* verifies. TTL defaults to 5 minutes — long enough to type the code,
+	* short enough that an abandoned login can't be picked up later.
+	*/
+	signTotpChallengeToken(payload: TotpChallengeClaims, ttlSec?: number): string;
+	/**
+	* A short-lived proof that the signed-in user just re-entered their password
+	* or used a passkey. Sensitive self-service actions (linking a sign-in
+	* account, disabling 2FA, removing a passkey, minting an admin token)
+	* require one. `kind: 'reauth'` keeps it from ever being a bearer.
+	*/
+	signReauthToken(claims: ReauthClaims, ttlSec?: number): string;
+	/** Decode a re-authentication proof, or `null` (forged, expired, another kind). */
+	verifyReauthToken(token: string): ReauthClaims | null;
+	/**
+	* Verify + decode a TOTP challenge token. Returns `null` for any
+	* failure (invalid signature, expired, wrong `kind`, missing
+	* claims). The caller MUST also verify the 6-digit code against
+	* `totpManager.verify(userId, code)` before minting the real
+	* session — this method validates the bridge transport only.
+	*/
+	verifyTotpChallengeToken(token: string): TotpChallengeClaims | null;
 }
 /** Seconds a re-authentication proof lasts (`signReauthToken`). */
 export declare const REAUTH_TTL_SEC = 300;
 /** What a re-authentication proof says: who proved it, from which session, how. */
 export interface ReauthClaims {
-    readonly userId: string;
-    /** The login session it was proved in — a proof is spent only there. */
-    readonly sessionId?: string;
-    readonly method: 'password' | 'passkey';
+	readonly userId: string;
+	/** The login session it was proved in — a proof is spent only there. */
+	readonly sessionId?: string;
+	readonly method: "password" | "passkey";
 }
 /**
- * Derived from the cap schema rather than restated.
- *
- * This was a hand-written interface duplicating `SsoBridgeClaimsSchema`, and it
- * had already drifted: `codeChallenge` — the field that makes PKCE mandatory at
- * exchange — was in the schema and absent here, so the claim travelled through
- * a type that did not know it existed. That is the failure mode the repo's
- * `z.infer<>`-never-duplicate-a-shape rule exists to stop.
- */
+* Derived from the cap schema rather than restated.
+*
+* This was a hand-written interface duplicating `SsoBridgeClaimsSchema`, and it
+* had already drifted: `codeChallenge` — the field that makes PKCE mandatory at
+* exchange — was in the schema and absent here, so the claim travelled through
+* a type that did not know it existed. That is the failure mode the repo's
+* `z.infer<>`-never-duplicate-a-shape rule exists to stop.
+*/
 export type SsoBridgeClaims = z.infer<typeof SsoBridgeClaimsSchema>;
 export interface TotpChallengeClaims {
-    readonly userId: string;
-    readonly username: string;
-    readonly isAdmin: boolean;
-    /** The primary factor the user already proved — recorded on the session it leads to. */
-    readonly method?: 'password' | 'passkey' | 'sso';
+	readonly userId: string;
+	readonly username: string;
+	readonly isAdmin: boolean;
+	/** The primary factor the user already proved — recorded on the session it leads to. */
+	readonly method?: "password" | "passkey" | "sso";
 }

package/dist/auth/cidr.d.ts

@@ -1,22 +1,22 @@
 /** Strip an IPv4-mapped IPv6 prefix and a zone id, so ranges see a clean address. */
 export declare function normalizeIp(ip: string): string;
 export interface ParsedCidr {
-    readonly network: string;
-    readonly prefix: number;
-    readonly family: 'ipv4' | 'ipv6';
+	readonly network: string;
+	readonly prefix: number;
+	readonly family: "ipv4" | "ipv6";
 }
 export interface ParsedCidrList {
-    readonly valid: readonly ParsedCidr[];
-    readonly invalid: readonly string[];
+	readonly valid: readonly ParsedCidr[];
+	readonly invalid: readonly string[];
 }
 /** Parse a list of CIDR strings; blanks are skipped, unparseable entries returned. */
 export declare function parseCidrList(entries: readonly string[]): ParsedCidrList;
 /** A stored setting as a string list — accepts a list, or one comma/space separated string. */
 export declare function readCidrSetting(value: unknown): readonly string[];
 export interface CidrMatcher {
-    contains(ip: string): boolean;
-    /** How many valid ranges the matcher holds (0 = matches nothing). */
-    readonly size: number;
+	contains(ip: string): boolean;
+	/** How many valid ranges the matcher holds (0 = matches nothing). */
+	readonly size: number;
 }
 /** A matcher over the VALID entries of `entries`; invalid ones match nothing. */
 export declare function createCidrMatcher(entries: readonly string[]): CidrMatcher;

package/dist/auth/external-identity-manager.d.ts

@@ -1,43 +1,55 @@
-import { SettingsStoreClient } from '@camstack/types';
+/**
+* External sign-in identities linked to local users (D782).
+*
+* An OIDC login names an identity `(provider, subject)` — the provider
+* instance's login-method id (`auth-oidc/authentik`) and the IdP's `sub`. It
+* signs in ONLY the user its owner explicitly linked it to: no
+* auto-provisioning, no email matching, no group mapping.
+*
+* The row id is the identity itself (`JSON.stringify([provider, subject])`),
+* so the collection's primary key is what makes "one identity → one user" a
+* storage invariant rather than a check that a race could slip past.
+*/
+import type { SettingsStoreClient } from "@camstack/types";
 export interface ExternalIdentityRecord {
-    readonly provider: string;
-    readonly subject: string;
-    /** Verified `iss` the identity was linked under. */
-    readonly issuer: string;
-    readonly userId: string;
-    readonly label?: string;
-    readonly linkedAt: number;
+	readonly provider: string;
+	readonly subject: string;
+	/** Verified `iss` the identity was linked under. */
+	readonly issuer: string;
+	readonly userId: string;
+	readonly label?: string;
+	readonly linkedAt: number;
 }
 export interface ExternalIdentityKey {
-    readonly provider: string;
-    readonly subject: string;
+	readonly provider: string;
+	readonly subject: string;
 }
 /** The identity is already linked to a different user. */
 export declare class ExternalIdentityConflictError extends Error {
-    constructor();
+	constructor();
 }
 export declare class ExternalIdentityManager {
-    private readonly store;
-    constructor(store: SettingsStoreClient);
-    private find;
-    /** The link of `(provider, subject)`, or `null`. */
-    findLink(provider: string, subject: string): Promise<ExternalIdentityRecord | null>;
-    /** The user `(provider, subject)` is linked to, or `null`. */
-    findUser(provider: string, subject: string): Promise<string | null>;
-    listForUser(userId: string): Promise<readonly ExternalIdentityRecord[]>;
-    /**
-     * Link `(provider, subject)` to `userId`. Idempotent for the same user;
-     * {@link ExternalIdentityConflictError} when another user holds it.
-     */
-    link(input: ExternalIdentityKey & {
-        userId: string;
-        issuer: string;
-        label?: string;
-    }): Promise<void>;
-    /** Remove one link of `userId`; `false` when that user did not hold it. */
-    unlink(input: ExternalIdentityKey & {
-        userId: string;
-    }): Promise<boolean>;
-    /** Delete every link of a user being deleted. Returns how many were removed. */
-    removeAllForUser(userId: string): Promise<number>;
+	private readonly store;
+	constructor(store: SettingsStoreClient);
+	private find;
+	/** The link of `(provider, subject)`, or `null`. */
+	findLink(provider: string, subject: string): Promise<ExternalIdentityRecord | null>;
+	/** The user `(provider, subject)` is linked to, or `null`. */
+	findUser(provider: string, subject: string): Promise<string | null>;
+	listForUser(userId: string): Promise<readonly ExternalIdentityRecord[]>;
+	/**
+	* Link `(provider, subject)` to `userId`. Idempotent for the same user;
+	* {@link ExternalIdentityConflictError} when another user holds it.
+	*/
+	link(input: ExternalIdentityKey & {
+		userId: string;
+		issuer: string;
+		label?: string;
+	}): Promise<void>;
+	/** Remove one link of `userId`; `false` when that user did not hold it. */
+	unlink(input: ExternalIdentityKey & {
+		userId: string;
+	}): Promise<boolean>;
+	/** Delete every link of a user being deleted. Returns how many were removed. */
+	removeAllForUser(userId: string): Promise<number>;
 }

package/dist/auth/jwt-signing-key.d.ts

@@ -1,23 +1,23 @@
-import { SecretsAccess } from '@camstack/types';
+import { type SecretsAccess } from "@camstack/types";
 /** The keychain owner of every system-held secret. */
 export declare const SYSTEM_SECRET_OWNER = "system";
 /** `secret://system/global/jwtSigningKey`. */
 export declare const JWT_SIGNING_KEY_REF: string;
 export type JwtSigningKeyState = {
-    readonly state: 'ready';
-    readonly key: string;
+	readonly state: "ready";
+	readonly key: string;
 } | {
-    readonly state: 'unavailable';
-    readonly reason: string;
+	readonly state: "unavailable";
+	readonly reason: string;
 };
 /** Sessions cannot be minted or verified: the signing key is not loaded. */
 export declare class JwtSigningKeyUnavailableError extends Error {
-    readonly reason: string;
-    constructor(reason: string);
+	readonly reason: string;
+	constructor(reason: string);
 }
 /** Where an `AuthManager` gets its key. `current()` throws while there is none. */
 export interface JwtSigningKeySource {
-    current(): string;
+	current(): string;
 }
 /** Register the loaded (or unloadable) key. Called by the hub's `local-auth`. */
 export declare function setProcessJwtSigningKey(state: JwtSigningKeyState): void;
@@ -31,12 +31,12 @@ export declare function staticJwtSigningKey(key: string): JwtSigningKeySource;
 /** 32 random bytes, hex. */
 export declare function generateJwtSigningKey(): string;
 export interface LoadJwtSigningKeyDeps {
-    /** A keychain handle acting for owner `system`. */
-    readonly secrets: SecretsAccess;
-    readonly generate?: () => string;
+	/** A keychain handle acting for owner `system`. */
+	readonly secrets: SecretsAccess;
+	readonly generate?: () => string;
 }
 /**
- * Read the key from the keychain; generate and store one ONLY when the
- * keychain answers that none exists. Never throws.
- */
+* Read the key from the keychain; generate and store one ONLY when the
+* keychain answers that none exists. Never throws.
+*/
 export declare function loadJwtSigningKey(deps: LoadJwtSigningKeyDeps): Promise<JwtSigningKeyState>;