camusdb 0.1.0

package/dist/auth/credentials.d.ts

@@ -0,0 +1,30 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * What the driver was given to authenticate with.
+ *
+ * Either a user and password pair, which the driver exchanges for a short-lived bearer token and
+ * re-exchanges when the token expires, or a token the caller obtained elsewhere and hands over as
+ * written. A value with neither is `NO_CREDENTIALS`: the driver sends no `Authorization` header at
+ * all, which is correct against a server with authentication off — the default.
+ */
+export interface CamusCredentials {
+    /** The user to authenticate as, or undefined when a token was supplied directly. */
+    readonly user?: string | undefined;
+    /** The user's password. It is only ever sent to `/login`, never with an ordinary statement. */
+    readonly password?: string | undefined;
+    /** A token obtained elsewhere, used as written. It excludes `user`. */
+    readonly accessToken?: string | undefined;
+}
+export declare const NO_CREDENTIALS: CamusCredentials;
+export declare function credentialsFromPassword(user: string, password: string): CamusCredentials;
+export declare function credentialsFromToken(accessToken: string): CamusCredentials;
+/** True when there is anything to authenticate with. */
+export declare function hasCredentials(credentials: CamusCredentials): boolean;
+/** True when the driver can mint a fresh token on its own, because it holds the password. */
+export declare function canRenew(credentials: CamusCredentials): boolean;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/auth/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/auth/credentials.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,cAAc,EAAE,gBAAoC,CAAC;AAElE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAExF;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAE1E;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAKrE;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAE/D"}

package/dist/auth/credentials.js

@@ -0,0 +1,23 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+export const NO_CREDENTIALS = Object.freeze({});
+export function credentialsFromPassword(user, password) {
+    return { user, password };
+}
+export function credentialsFromToken(accessToken) {
+    return { accessToken };
+}
+/** True when there is anything to authenticate with. */
+export function hasCredentials(credentials) {
+    return ((credentials.user !== undefined && credentials.user.length > 0) ||
+        (credentials.accessToken !== undefined && credentials.accessToken.length > 0));
+}
+/** True when the driver can mint a fresh token on its own, because it holds the password. */
+export function canRenew(credentials) {
+    return credentials.user !== undefined && credentials.user.length > 0 && credentials.password !== undefined;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/auth/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/auth/credentials.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,MAAM,CAAC,MAAM,cAAc,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAElE,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,QAAgB;IACpE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO,EAAE,WAAW,EAAE,CAAC;AACzB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,WAA6B;IAC1D,OAAO,CACL,CAAC,WAAW,CAAC,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC/D,CAAC,WAAW,CAAC,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAC9E,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,QAAQ,CAAC,WAA6B;IACpD,OAAO,WAAW,CAAC,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,CAAC;AAC7G,CAAC"}

package/dist/auth/login-client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * A minted bearer token and, when the server reported one, how long it is good for.
+ *
+ * `expiresInMs` is a duration rather than an instant on purpose: the server measures it when it
+ * issues the reply, so a client whose clock disagrees with the server's still renews on time. It
+ * is `undefined` against a server that predates the field, in which case the driver falls back to
+ * its configured token lifetime.
+ */
+export interface CamusLoginResult {
+    readonly token: string;
+    readonly expiresInMs?: number | undefined;
+}
+/**
+ * The credential-exchange half of the protocol.
+ *
+ * It is kept apart from the statement transport because it is the one exchange reachable without a
+ * token: REST serves it at `/login`, gRPC on the dedicated `CamusAuth` service, and each transport
+ * implements it against its own endpoint. Keeping it a separate interface makes that
+ * unauthenticated surface explicit, and lets the token provider be tested without a server.
+ */
+export interface CamusLoginClient {
+    /**
+     * Exchanges a password for a short-lived bearer token.
+     *
+     * @throws {CamusError} `CADB0516` when the credentials are rejected.
+     */
+    login(endpoint: string, user: string, password: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusLoginResult>;
+    /** Revokes a token on the server. */
+    logout(endpoint: string, token: string, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=login-client.d.ts.map

package/dist/auth/login-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-client.d.ts","sourceRoot":"","sources":["../../src/auth/login-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE7B,qCAAqC;IACrC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtG"}

package/dist/auth/login-client.js

@@ -0,0 +1,8 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+export {};
+//# sourceMappingURL=login-client.js.map

package/dist/auth/login-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-client.js","sourceRoot":"","sources":["../../src/auth/login-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/auth/rest-login-client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { CamusLoginClient, CamusLoginResult } from './login-client.js';
+/**
+ * The login client over the server's HTTP `/login` and `/logout` routes — the only routes exempt
+ * from the server's own authentication middleware, and the only place a password is ever put on
+ * the wire.
+ */
+export declare class RestLoginClient implements CamusLoginClient {
+    login(endpoint: string, user: string, password: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusLoginResult>;
+    logout(endpoint: string, token: string, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=rest-login-client.d.ts.map

package/dist/auth/rest-login-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-login-client.d.ts","sourceRoot":"","sources":["../../src/auth/rest-login-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAW5E;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IAChD,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC;IA0BtB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAgB3G"}

package/dist/auth/rest-login-client.js

@@ -0,0 +1,71 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { CamusError } from '../errors.js';
+import { CamusErrorCode } from '../error-codes.js';
+import { asNumber, parseLossless } from '../json.js';
+import { readBody, sendHttp, translateErrorBody } from '../transport/http.js';
+/**
+ * The login client over the server's HTTP `/login` and `/logout` routes — the only routes exempt
+ * from the server's own authentication middleware, and the only place a password is ever put on
+ * the wire.
+ */
+export class RestLoginClient {
+    async login(endpoint, user, password, timeoutSeconds, signal) {
+        const { response } = await sendHttp(undefined, {
+            endpoint,
+            path: ['login'],
+            method: 'POST',
+            body: { user, password },
+            timeoutSeconds,
+            signal,
+        });
+        const text = await readBody(response);
+        if (!response.ok)
+            throw translateErrorBody(response.status, text);
+        const body = (text.length > 0 ? parseLossless(text) : null);
+        if (body === null || body.status !== 'ok' || body.token === undefined || body.token.length === 0) {
+            throw new CamusError(body?.code ?? CamusErrorCode.AuthenticationFailed, body?.message ?? 'Authentication failed');
+        }
+        return { token: body.token, expiresInMs: readExpiryMs(body) };
+    }
+    async logout(endpoint, token, timeoutSeconds, signal) {
+        const { response } = await sendHttp(undefined, {
+            endpoint,
+            path: ['logout'],
+            method: 'POST',
+            token,
+            timeoutSeconds,
+            signal,
+        });
+        if (!response.ok)
+            throw translateErrorBody(response.status, await readBody(response));
+        // The body carries nothing this driver reads, but it must be drained so the connection returns
+        // to the pool instead of staying half-read.
+        await readBody(response);
+    }
+}
+/**
+ * How long a minted token is good for.
+ *
+ * The server-measured duration is preferred, because it is immune to clock skew between client and
+ * server. The absolute instant is the fallback, and it is not. A server that reports neither leaves
+ * the driver on its configured fallback lifetime. A value that is not positive is treated as
+ * absent rather than as an already-dead token.
+ */
+function readExpiryMs(body) {
+    const seconds = asNumber(body.expiresInSeconds, 0);
+    if (seconds > 0)
+        return seconds * 1000;
+    const expiresAt = asNumber(body.expiresAtUnixMs, 0);
+    if (expiresAt > 0) {
+        const remaining = expiresAt - Date.now();
+        if (remaining > 0)
+            return remaining;
+    }
+    return undefined;
+}
+//# sourceMappingURL=rest-login-client.js.map

package/dist/auth/rest-login-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-login-client.js","sourceRoot":"","sources":["../../src/auth/rest-login-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAY9E;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,KAAK,CACT,QAAgB,EAChB,IAAY,EACZ,QAAgB,EAChB,cAAsB,EACtB,MAAoB;QAEpB,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE;YAC7C,QAAQ;YACR,IAAI,EAAE,CAAC,OAAO,CAAC;YACf,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxB,cAAc;YACd,MAAM;SACP,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAEtC,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAElE,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAA6B,CAAC;QAExF,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjG,MAAM,IAAI,UAAU,CAClB,IAAI,EAAE,IAAI,IAAI,cAAc,CAAC,oBAAoB,EACjD,IAAI,EAAE,OAAO,IAAI,uBAAuB,CACzC,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,KAAa,EAAE,cAAsB,EAAE,MAAoB;QACxF,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE;YAC7C,QAAQ;YACR,IAAI,EAAE,CAAC,QAAQ,CAAC;YAChB,MAAM,EAAE,MAAM;YACd,KAAK;YACL,cAAc;YACd,MAAM;SACP,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAEtF,+FAA+F;QAC/F,4CAA4C;QAC5C,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,IAAuB;IAC3C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAEnD,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,OAAO,GAAG,IAAI,CAAC;IAEvC,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;IAEpD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,MAAM,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzC,IAAI,SAAS,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;IACtC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/auth/token-provider.d.ts

@@ -0,0 +1,123 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { CamusCredentials } from './credentials.js';
+import type { CamusLoginClient } from './login-client.js';
+/** The fallback token lifetime, comfortably inside the server's 15-minute default. */
+export declare const DEFAULT_TOKEN_LIFETIME_MS = 600000;
+/**
+ * Owns a client's bearer token: mints it from the configured credentials on first use, hands the
+ * same token to every request until it goes stale, and mints a new one when it does.
+ *
+ * One provider is shared by every client that presents the same identity to the same deployment,
+ * so a pool of clients performs one login rather than one each. Password verification is
+ * deliberately expensive on the server — PBKDF2 with 600,000 iterations by default — and rate
+ * limited per account, so a login stampede is exactly what must be avoided.
+ *
+ * **Single flight.** Concurrent callers that find no usable token await one promise; the winner
+ * logs in and the rest observe its result instead of issuing their own login.
+ *
+ * **Renewal.** The login reply reports how long the token is good for, and the provider renews at
+ * 80% of that. Against a server that predates the field it falls back to its own conservative
+ * lifetime. That proactive renewal is the primary path. `invalidate`, driven by a `CADB0516` from
+ * a real request, is the backstop for what a clock cannot predict: a rotated password, a dropped
+ * user, a logout from elsewhere, or a server whose token lifetime is shorter than the fallback.
+ *
+ * A token supplied directly is used as written and never renewed — the driver has no password to
+ * mint a replacement with — so a `CADB0516` on that path reaches the caller rather than a retry.
+ */
+export declare class CamusTokenProvider {
+    private static readonly shared;
+    /**
+     * The process-wide provider for an identity, built on first use. Keyed by credentials rather
+     * than by the whole configuration, so clients that differ only in database or timeout share one
+     * token.
+     */
+    static forKey(key: string, factory: () => CamusTokenProvider): CamusTokenProvider;
+    /** @internal Test hook: drops every shared provider. */
+    static resetShared(): void;
+    /**
+     * A per-process random salt for `sharingKey`.
+     *
+     * The key lives in a map for the life of the process, and an unsalted hash of a password is an
+     * offline verifier for anyone who can read process memory. The key only has to be stable inside
+     * one process, so a salt costs nothing.
+     */
+    private static readonly sharingSalt;
+    /**
+     * A stable, non-reversible identity for a credential set plus a deployment. It is hashed, and
+     * salted per process, so a long-lived map key neither holds a plaintext password nor can be
+     * tested against a guessed one outside this process.
+     */
+    static sharingKey(credentials: CamusCredentials, deploymentKey: string): string;
+    private credentials;
+    private token;
+    private renewAfter;
+    private readonly resolveLoginClient;
+    private readonly resolveEndpoint;
+    private readonly resolveTimeoutSeconds;
+    private readonly lifetimeMs;
+    /** The single login in flight, if any. Every racing caller awaits this same promise. */
+    private inFlight;
+    /** @internal Test hook: the wall clock this provider reads. */
+    clock: () => number;
+    constructor(init: {
+        credentials: CamusCredentials;
+        resolveLoginClient: () => CamusLoginClient | Promise<CamusLoginClient>;
+        resolveEndpoint: () => string;
+        resolveTimeoutSeconds: () => number;
+        lifetimeMs?: number;
+    });
+    /**
+     * True when this client has anything to authenticate with. When false the driver sends no
+     * `Authorization` header, which is what a server with authentication off expects.
+     */
+    get isEnabled(): boolean;
+    /** True when the provider holds a password and can therefore replace a rejected token. */
+    get canRenew(): boolean;
+    /**
+     * The cached token, without triggering a login. The gRPC batch-stream factory reads it, because
+     * it builds a stream synchronously; every such call site awaits `getToken` first, so the cache
+     * is warm by then.
+     */
+    get currentToken(): string | undefined;
+    /**
+     * A usable bearer token, logging in when there is none or the cached one has aged out. Reports
+     * `undefined` when no credentials are configured.
+     */
+    getToken(signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * Discards a token so the next `getToken` mints a new one.
+     *
+     * Comparing against the cached value keeps a late rejection of an already-replaced token from
+     * throwing away the good one a concurrent caller just obtained. It does nothing when the token
+     * cannot be renewed, so the caller reports the failure instead of looping.
+     */
+    invalidate(staleToken: string | undefined): void;
+    /**
+     * Authenticates explicitly, replacing whatever credentials were configured, and reports the
+     * minted token. Any cached token is dropped.
+     */
+    login(user: string, password: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * Revokes the cached token on the server and forgets it. The configured credentials are kept, so
+     * a later statement authenticates again on its own: this ends a session, it does not switch
+     * authentication off. It does nothing when no token has been minted.
+     */
+    logout(signal?: AbortSignal): Promise<void>;
+    private tryGetCached;
+    private loginOnce;
+    /**
+     * When to mint the next token.
+     *
+     * The server's reported lifetime is authoritative — its own setting is configurable and may be
+     * shorter than any value the driver defaults to — so the provider renews at 80% of it, leaving
+     * headroom for the request that carries the token to finish. Without a reported value it falls
+     * back to the configured lifetime, which is already conservative.
+     */
+    private renewalDelayMs;
+}
+//# sourceMappingURL=token-provider.d.ts.map

package/dist/auth/token-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-provider.d.ts","sourceRoot":"","sources":["../../src/auth/token-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,mBAAmB,CAAC;AAE5E,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAA4C;IAE1E;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,kBAAkB,GAAG,kBAAkB;IAIjF,wDAAwD;IACxD,MAAM,CAAC,WAAW,IAAI,IAAI;IAI1B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAEtD;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAW/E,OAAO,CAAC,WAAW,CAAmB;IAEtC,OAAO,CAAC,KAAK,CAAqB;IAElC,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqD;IAExF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAE/C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAe;IAErD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAA8B;IAE9C,+DAA+D;IAC/D,KAAK,EAAE,MAAM,MAAM,CAAoB;gBAE3B,IAAI,EAAE;QAChB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,kBAAkB,EAAE,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACvE,eAAe,EAAE,MAAM,MAAM,CAAC;QAC9B,qBAAqB,EAAE,MAAM,MAAM,CAAC;QACpC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAYD;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,0FAA0F;IAC1F,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;OAGG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAajE;;;;;;OAMG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAShD;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAalF;;;;OAIG;IACG,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjD,OAAO,CAAC,YAAY;YAON,SAAS;IA6BvB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;CAMvB"}

package/dist/auth/token-provider.js

@@ -0,0 +1,209 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { createHmac, randomBytes } from 'node:crypto';
+import { CamusError } from '../errors.js';
+import { CamusErrorCode } from '../error-codes.js';
+import { SharedRegistry } from '../shared-registry.js';
+import { canRenew, credentialsFromPassword, hasCredentials } from './credentials.js';
+/** The fallback token lifetime, comfortably inside the server's 15-minute default. */
+export const DEFAULT_TOKEN_LIFETIME_MS = 600_000;
+/**
+ * Owns a client's bearer token: mints it from the configured credentials on first use, hands the
+ * same token to every request until it goes stale, and mints a new one when it does.
+ *
+ * One provider is shared by every client that presents the same identity to the same deployment,
+ * so a pool of clients performs one login rather than one each. Password verification is
+ * deliberately expensive on the server — PBKDF2 with 600,000 iterations by default — and rate
+ * limited per account, so a login stampede is exactly what must be avoided.
+ *
+ * **Single flight.** Concurrent callers that find no usable token await one promise; the winner
+ * logs in and the rest observe its result instead of issuing their own login.
+ *
+ * **Renewal.** The login reply reports how long the token is good for, and the provider renews at
+ * 80% of that. Against a server that predates the field it falls back to its own conservative
+ * lifetime. That proactive renewal is the primary path. `invalidate`, driven by a `CADB0516` from
+ * a real request, is the backstop for what a clock cannot predict: a rotated password, a dropped
+ * user, a logout from elsewhere, or a server whose token lifetime is shorter than the fallback.
+ *
+ * A token supplied directly is used as written and never renewed — the driver has no password to
+ * mint a replacement with — so a `CADB0516` on that path reaches the caller rather than a retry.
+ */
+export class CamusTokenProvider {
+    static shared = new SharedRegistry();
+    /**
+     * The process-wide provider for an identity, built on first use. Keyed by credentials rather
+     * than by the whole configuration, so clients that differ only in database or timeout share one
+     * token.
+     */
+    static forKey(key, factory) {
+        return CamusTokenProvider.shared.get(key, factory);
+    }
+    /** @internal Test hook: drops every shared provider. */
+    static resetShared() {
+        CamusTokenProvider.shared.clear();
+    }
+    /**
+     * A per-process random salt for `sharingKey`.
+     *
+     * The key lives in a map for the life of the process, and an unsalted hash of a password is an
+     * offline verifier for anyone who can read process memory. The key only has to be stable inside
+     * one process, so a salt costs nothing.
+     */
+    static sharingSalt = randomBytes(32);
+    /**
+     * A stable, non-reversible identity for a credential set plus a deployment. It is hashed, and
+     * salted per process, so a long-lived map key neither holds a plaintext password nor can be
+     * tested against a guessed one outside this process.
+     */
+    static sharingKey(credentials, deploymentKey) {
+        const material = [
+            credentials.user ?? '',
+            credentials.password ?? '',
+            credentials.accessToken ?? '',
+            deploymentKey,
+        ].join('\n');
+        return createHmac('sha256', CamusTokenProvider.sharingSalt).update(material, 'utf8').digest('hex');
+    }
+    credentials;
+    token;
+    renewAfter;
+    resolveLoginClient;
+    resolveEndpoint;
+    resolveTimeoutSeconds;
+    lifetimeMs;
+    /** The single login in flight, if any. Every racing caller awaits this same promise. */
+    inFlight;
+    /** @internal Test hook: the wall clock this provider reads. */
+    clock = () => Date.now();
+    constructor(init) {
+        this.credentials = init.credentials;
+        this.resolveLoginClient = init.resolveLoginClient;
+        this.resolveEndpoint = init.resolveEndpoint;
+        this.resolveTimeoutSeconds = init.resolveTimeoutSeconds;
+        this.lifetimeMs = init.lifetimeMs ?? DEFAULT_TOKEN_LIFETIME_MS;
+        // A token supplied directly is the cached token, and never ages out on this side.
+        this.token = init.credentials.accessToken;
+        this.renewAfter = Number.POSITIVE_INFINITY;
+    }
+    /**
+     * True when this client has anything to authenticate with. When false the driver sends no
+     * `Authorization` header, which is what a server with authentication off expects.
+     */
+    get isEnabled() {
+        return hasCredentials(this.credentials);
+    }
+    /** True when the provider holds a password and can therefore replace a rejected token. */
+    get canRenew() {
+        return canRenew(this.credentials);
+    }
+    /**
+     * The cached token, without triggering a login. The gRPC batch-stream factory reads it, because
+     * it builds a stream synchronously; every such call site awaits `getToken` first, so the cache
+     * is warm by then.
+     */
+    get currentToken() {
+        return this.token;
+    }
+    /**
+     * A usable bearer token, logging in when there is none or the cached one has aged out. Reports
+     * `undefined` when no credentials are configured.
+     */
+    async getToken(signal) {
+        const cached = this.tryGetCached();
+        if (cached !== undefined)
+            return cached;
+        if (!this.isEnabled)
+            return undefined;
+        // A caller that arrives during a login awaits that login rather than issuing its own.
+        this.inFlight ??= this.loginOnce(signal).finally(() => {
+            this.inFlight = undefined;
+        });
+        return this.inFlight;
+    }
+    /**
+     * Discards a token so the next `getToken` mints a new one.
+     *
+     * Comparing against the cached value keeps a late rejection of an already-replaced token from
+     * throwing away the good one a concurrent caller just obtained. It does nothing when the token
+     * cannot be renewed, so the caller reports the failure instead of looping.
+     */
+    invalidate(staleToken) {
+        if (staleToken === undefined || staleToken.length === 0)
+            return;
+        if (!this.canRenew)
+            return;
+        if (this.token !== staleToken)
+            return;
+        this.token = undefined;
+        this.renewAfter = 0;
+    }
+    /**
+     * Authenticates explicitly, replacing whatever credentials were configured, and reports the
+     * minted token. Any cached token is dropped.
+     */
+    async login(user, password, signal) {
+        this.credentials = credentialsFromPassword(user, password);
+        this.token = undefined;
+        this.renewAfter = 0;
+        const pending = this.loginOnce(signal).finally(() => {
+            this.inFlight = undefined;
+        });
+        this.inFlight = pending;
+        return pending;
+    }
+    /**
+     * Revokes the cached token on the server and forgets it. The configured credentials are kept, so
+     * a later statement authenticates again on its own: this ends a session, it does not switch
+     * authentication off. It does nothing when no token has been minted.
+     */
+    async logout(signal) {
+        const revoked = this.token;
+        this.token = undefined;
+        this.renewAfter = 0;
+        if (revoked === undefined || revoked.length === 0)
+            return;
+        const client = await this.resolveLoginClient();
+        await client.logout(this.resolveEndpoint(), revoked, this.resolveTimeoutSeconds(), signal);
+    }
+    tryGetCached() {
+        if (!this.isEnabled)
+            return undefined;
+        if (this.token === undefined)
+            return undefined;
+        return this.clock() < this.renewAfter ? this.token : undefined;
+    }
+    async loginOnce(signal) {
+        // Re-checked inside the single-flight gate: the caller that queued behind the winner finds the
+        // token it minted.
+        const cached = this.tryGetCached();
+        if (cached !== undefined)
+            return cached;
+        if (!this.canRenew) {
+            throw new CamusError(CamusErrorCode.AuthenticationFailed, 'The supplied access token was rejected and this client has no credentials to obtain a new one.');
+        }
+        const client = await this.resolveLoginClient();
+        const minted = await client.login(this.resolveEndpoint(), this.credentials.user, this.credentials.password, this.resolveTimeoutSeconds(), signal);
+        this.token = minted.token;
+        this.renewAfter = this.clock() + this.renewalDelayMs(minted.expiresInMs);
+        return minted.token;
+    }
+    /**
+     * When to mint the next token.
+     *
+     * The server's reported lifetime is authoritative — its own setting is configurable and may be
+     * shorter than any value the driver defaults to — so the provider renews at 80% of it, leaving
+     * headroom for the request that carries the token to finish. Without a reported value it falls
+     * back to the configured lifetime, which is already conservative.
+     */
+    renewalDelayMs(reported) {
+        if (reported === undefined)
+            return this.lifetimeMs;
+        const renewal = reported * 0.8;
+        return renewal > 0 ? renewal : 1000;
+    }
+}
+//# sourceMappingURL=token-provider.js.map

package/dist/auth/token-provider.js.map

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