@opengeni/db 0.14.3 → 0.17.1

package/dist/codex-token-resolver.d.ts

@@ -0,0 +1,64 @@
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import { type CodexTokenSnapshot, type CodexUsagePayload, type CodexFetch, type CodexRateLimitResetCreditsDetails, type ResetCreditFetchFailureReason, refreshCodexToken } from "@opengeni/codex";
+import { encryptEnvironmentValue } from "./environment-crypto";
+import { loadCodexCredentialForRun, recordCodexTokenRefresh, setCodexCredentialStatus, withCodexCredentialRefreshLock, type Database } from "./index";
+export type CodexTokenDeadlineClock = {
+    setTimeout: (callback: () => void, delayMs: number) => ReturnType<typeof globalThis.setTimeout>;
+    clearTimeout: (handle: ReturnType<typeof globalThis.setTimeout>) => void;
+};
+export type CodexTokenDeadlineOptions = {
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    clock?: CodexTokenDeadlineClock | undefined;
+};
+/**
+ * Bound a refresh promise without abandoning its rejection handler when the
+ * deadline or cancellation wins. The provider promise is observed exactly
+ * once, while the observer itself always fulfills, so a late provider failure
+ * cannot become an unhandled rejection or replace the authoritative outcome.
+ */
+export declare function withCodexTokenDeadline<T>(operation: Promise<T>, options?: CodexTokenDeadlineOptions): Promise<T>;
+export type CodexAuthDeps = {
+    loadCredential: typeof loadCodexCredentialForRun;
+    recordRefresh: typeof recordCodexTokenRefresh;
+    setStatus: typeof setCodexCredentialStatus;
+    refresh: typeof refreshCodexToken;
+    encrypt: typeof encryptEnvironmentValue;
+    keyBytes: typeof environmentsEncryptionKeyBytes;
+    withRefreshLock: typeof withCodexCredentialRefreshLock;
+};
+export declare function buildCodexTokenResolver(db: Database, settings: Settings, workspaceId: string, credentialId: string, deps?: CodexAuthDeps): {
+    getToken: () => Promise<CodexTokenSnapshot>;
+    refresh: () => Promise<CodexTokenSnapshot>;
+};
+/**
+ * THE single per-account usage path both the api route and an (optional) worker
+ * poll call, so the refresh discipline and the cache-write can never drift.
+ *
+ *   1. resolve a REFRESHING bearer for THIS account (proactive staleness refresh,
+ *      single-flight, (id,version) CAS-persist) — this is what stops an idle
+ *      account's expired JWT from 401-ing the usage read.
+ *   2. fetch GET /wham/usage with that bearer.
+ *   3. normalize (§3) into the P2/P3 contract.
+ *   4. on any windows present, write the five usage-cache columns (the TTL clock).
+ *
+ * A refresh that stamps needs_relogin returns { status:"error", reason } and never
+ * hits the provider; a transient refresh error returns a plain error payload.
+ */
+export declare function fetchCodexUsageForAccount(db: Database, settings: Settings, workspaceId: string, credentialId: string, fetchImpl?: CodexFetch): Promise<CodexUsagePayload>;
+export type CodexRateLimitResetCreditsAccountResult = {
+    ok: true;
+    status: number;
+    details: CodexRateLimitResetCreditsDetails;
+} | {
+    ok: false;
+    status: number;
+    reason: ResetCreditFetchFailureReason | "needs_relogin";
+};
+/**
+ * Fresh detailed reset-credit inventory for one exact workspace credential.
+ * The token is refreshed through the same resolver as usage and never escapes
+ * this server-side function. Detailed rows are returned to the route only and
+ * are never persisted as redemption authority.
+ */
+export declare function fetchCodexRateLimitResetCreditsForAccount(db: Database, settings: Settings, workspaceId: string, credentialId: string, fetchImpl?: CodexFetch): Promise<CodexRateLimitResetCreditsAccountResult>;

package/dist/connection-token-resolver.d.ts

@@ -0,0 +1,90 @@
+import { environmentsEncryptionKeyBytes, type McpServerConnectionRef, type Settings } from "@opengeni/config";
+import type { ConnectionCredentialsPort, McpConnectionResourceScope, McpCredentialAuthNeededReason, McpCredentialsRequest, TurnInitiator, TurnInitiatorContext } from "@opengeni/contracts";
+import { type DnsLookup, type FetchLike } from "@opengeni/network";
+export { isPrivateAddress } from "@opengeni/network";
+import { encryptEnvironmentValue } from "./environment-crypto";
+import { loadConnectionCredentialForBroker, recordConnectionTokenRefresh, recordConnectionUsed, setConnectionStatus, type ConnectionCredentialForBroker, type Database } from "./index";
+export type ResolveConnectionCredentialResult = {
+    status: "ok";
+    headers: Record<string, string>;
+    connectionId: string;
+    expiresAt?: Date | null;
+} | {
+    status: "auth_needed";
+    reason: McpCredentialAuthNeededReason;
+    providerDomain: string;
+    provider?: string;
+    connectionId?: string;
+    scopes?: string[];
+    resource?: string;
+    selectedResources?: McpConnectionResourceScope[];
+    authorizationUrl?: string;
+};
+export type ResolveConnectionCredentialInput = {
+    workspaceId: string;
+    subjectId?: string;
+    serverId: string;
+    toolName?: string;
+    /** @deprecated Use toolName. Retained for the API's pre-existing broker call shape. */
+    toolId?: string;
+    connectionRef: McpServerConnectionRef;
+    /** Exact MCP destination whose request would receive the resolved headers. */
+    destinationUrl: string;
+    forceRefresh?: boolean;
+};
+export type HostMcpCredentialResolverContext = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    rootSessionId: string;
+    turnId: string;
+    attemptId: string | null;
+    executionGeneration: number;
+    initiator: TurnInitiator;
+    initiatorContext: TurnInitiatorContext;
+    surface: McpCredentialsRequest["surface"];
+};
+export declare class HostMcpCredentialScopeError extends Error {
+    constructor(field: "accountId" | "workspaceId" | "sessionId");
+}
+export declare class HostMcpCredentialBindingError extends Error {
+    constructor(field: "provider" | "providerDomain" | "connectionId" | "scopes" | "resource" | "selectedResources" | "destinationUrl");
+}
+/**
+ * Adapts the public embedding credential port to the runtime's connection
+ * resolver contract. Scope echoes are checked before credential headers can
+ * reach a request; the returned object is a fresh copy so a host cannot mutate
+ * headers after resolution.
+ */
+export declare function buildHostConnectionTokenResolver(resolve: NonNullable<ConnectionCredentialsPort["mcpCredentials"]>, context: HostMcpCredentialResolverContext): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult>;
+export type ConnectionBrokerDeps = {
+    loadCredential: typeof loadConnectionCredentialForBroker;
+    recordRefresh: typeof recordConnectionTokenRefresh;
+    setStatus: typeof setConnectionStatus;
+    recordUsed: typeof recordConnectionUsed;
+    refresh: typeof refreshOAuthConnectionCredential;
+    encrypt: typeof encryptEnvironmentValue;
+    keyBytes: typeof environmentsEncryptionKeyBytes;
+    now: () => Date;
+};
+export type RefreshTransportOptions = {
+    fetchImpl?: FetchLike;
+    dnsLookup?: DnsLookup;
+};
+export declare function buildConnectionTokenResolver(db: Database, settings: Settings, deps?: ConnectionBrokerDeps): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult>;
+export declare class ConnectionRefreshHttpError extends Error {
+    readonly httpStatus: number;
+    constructor(httpStatus: number);
+}
+/**
+ * Normalizes an OAuth token_type into the Authorization scheme to send. RFC 6750
+ * says the scheme is case-insensitive, but some MCP servers (e.g. Linear) reject
+ * a lowercase `bearer` — so a `bearer`/`BEARER` (or absent) token_type is sent as
+ * the canonical `Bearer`. A non-bearer scheme is passed through unchanged.
+ */
+export declare function normalizeBearerScheme(tokenType: string | null | undefined): string;
+export declare function refreshOAuthConnectionCredential(cred: ConnectionCredentialForBroker, ref: McpServerConnectionRef, settings: Settings, transportOptions?: RefreshTransportOptions): Promise<{
+    credential: Record<string, unknown>;
+    expiresAt: Date | null;
+    grantedScopes?: string[];
+}>;

package/dist/environment-crypto.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Encrypts one workspace environment variable value with AES-256-GCM under an
+ * operator key held outside Postgres. Output format: `v1:<b64 iv>:<b64 ciphertext||tag>`.
+ */
+export declare function encryptEnvironmentValue(key: Uint8Array, plaintext: string): string;
+/**
+ * Decrypts a stored `v1:` value. Error messages never echo plaintext or
+ * ciphertext: unknown versions throw "unsupported environment value format",
+ * auth-tag mismatches throw "environment value decryption failed".
+ */
+export declare function decryptEnvironmentValue(key: Uint8Array, stored: string): string;

package/dist/event-payload-sanitizer.d.ts

@@ -0,0 +1,32 @@
+import { type SecretForRedaction } from "@opengeni/contracts";
+/**
+ * Strip NUL and repair invalid/lone UTF-16 surrogates in a single string.
+ * Returns the input unchanged (same reference) when it is already clean, so the
+ * common case allocates nothing.
+ */
+export declare function sanitizeEventString(value: string): string;
+/**
+ * Deep-walk a session event payload and sanitize every string value. Mirrors the
+ * shape of the worker redaction deep-walk: objects, arrays, and nested
+ * combinations are traversed; non-string leaves pass through untouched. Object
+ * keys are sanitized too -- they are jsonb-constrained the same as values.
+ */
+export type SanitizeEventPayloadOptions = {
+    /**
+     * Separately trusted, server-created retained-output evidence. Never populate
+     * this from a producer-controlled payload field.
+     */
+    fullEvidence?: unknown;
+    /** Exact runtime credential provenance to remove from keys and values. */
+    knownSecrets?: readonly SecretForRedaction[];
+};
+export declare function sanitizeEventPayload<T>(payload: T, options?: SanitizeEventPayloadOptions): T;
+/**
+ * Make model-facing conversation data safe for Postgres and secret-redacted.
+ *
+ * Conversation history is the replay source for the model, so this boundary
+ * retains protocol structure and non-sensitive diagnostics while removing
+ * credential-bearing fields and text before durable storage. It also performs
+ * the database-safety repair (NUL removal and UTF-16 repair).
+ */
+export declare function sanitizeModelPayload<T>(payload: T, knownSecrets?: readonly SecretForRedaction[]): T;