@opengeni/db 0.28.9 → 0.36.0

package/dist/browser-sessions.d.ts

@@ -0,0 +1,354 @@
+import { BrowserSession, InteractionControllerBinding, type BrowserSessionCapabilities as BrowserSessionCapabilitiesValue, type BrowserRevisionMaterialization as BrowserRevisionMaterializationValue, type BrowserSessionListResponse as BrowserSessionListResponseValue, type BrowserSessionMutationResponse as BrowserSessionMutationResponseValue, type InteractionError as InteractionErrorValue, type InteractionLifecycleOperationKind, type InteractionLifecycleOperationReceipt as InteractionLifecycleOperationReceiptValue, type InteractionPlacement, type NetworkRouteConfiguration as NetworkRouteConfigurationValue, type NetworkRouteConsistency as NetworkRouteConsistencyValue } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+import { type BrowserStateArtifactCommitInput } from "./browser-state-artifacts.js";
+import * as schema from "./schema.js";
+type BrowserSessionRow = typeof schema.browserSessions.$inferSelect;
+type InteractionOperationRow = typeof schema.interactionOperations.$inferSelect;
+export declare const MANAGED_BROWSER_SESSION_CAPABILITIES: {
+    semanticObservation: boolean;
+    screenshots: boolean;
+    liveFrames: boolean;
+    humanInput: boolean;
+    tabs: boolean;
+    downloads: boolean;
+    uploads: boolean;
+    clipboard: boolean;
+    permissions: boolean;
+    diagnostics: boolean;
+    rawCdp: boolean;
+    linkedComputer: boolean;
+    privateCheckpoint: boolean;
+    identityPublication: boolean;
+    parallelTargets: boolean;
+};
+export declare const ATTACHED_BROWSER_SESSION_CAPABILITIES: {
+    semanticObservation: boolean;
+    screenshots: boolean;
+    liveFrames: boolean;
+    humanInput: boolean;
+    tabs: boolean;
+    downloads: boolean;
+    uploads: boolean;
+    clipboard: boolean;
+    permissions: boolean;
+    diagnostics: boolean;
+    rawCdp: boolean;
+    linkedComputer: boolean;
+    privateCheckpoint: boolean;
+    identityPublication: boolean;
+    parallelTargets: boolean;
+};
+/** Remote Chromium controlled through the same native CDP driver. Files and
+ * portable profile state remain false because their bytes live on another host. */
+export declare const EXTERNAL_BROWSER_SESSION_CAPABILITIES: {
+    semanticObservation: boolean;
+    screenshots: boolean;
+    liveFrames: boolean;
+    humanInput: boolean;
+    tabs: boolean;
+    downloads: boolean;
+    uploads: boolean;
+    clipboard: boolean;
+    permissions: boolean;
+    diagnostics: boolean;
+    rawCdp: boolean;
+    linkedComputer: boolean;
+    privateCheckpoint: boolean;
+    identityPublication: boolean;
+    parallelTargets: boolean;
+};
+/** Measured against Lightpanda 0.3.5. Unsupported Chromium-only affordances
+ * remain false instead of being emulated or silently routed elsewhere. */
+export declare const LIGHTPANDA_BROWSER_SESSION_CAPABILITIES: {
+    semanticObservation: boolean;
+    screenshots: boolean;
+    liveFrames: boolean;
+    humanInput: boolean;
+    tabs: boolean;
+    downloads: boolean;
+    uploads: boolean;
+    clipboard: boolean;
+    permissions: boolean;
+    diagnostics: boolean;
+    rawCdp: boolean;
+    linkedComputer: boolean;
+    privateCheckpoint: boolean;
+    identityPublication: boolean;
+    parallelTargets: boolean;
+};
+export declare class BrowserSessionNotFoundError extends Error {
+    readonly name = "BrowserSessionNotFoundError";
+}
+export declare class BrowserSessionOperationConflictError extends Error {
+    readonly name = "BrowserSessionOperationConflictError";
+}
+export declare class BrowserSessionStateError extends Error {
+    readonly name = "BrowserSessionStateError";
+}
+export type PrepareBrowserSessionCreateInput = {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    associatedSessionId: string;
+    actorSubjectId: string;
+    name: string;
+    initialUrl: string | null;
+    placement: InteractionPlacement;
+    driverId: string;
+    engine: BrowserSessionRow["engine"];
+    headless: boolean;
+    identityId: string | null;
+    baseRevisionId: string | null;
+    networkRouteId?: string | null;
+    linkedComputerSessionId?: string | null;
+    resolveDefaultRevision?: boolean;
+    capabilities?: BrowserSessionCapabilitiesValue;
+};
+export type PrepareBrowserSessionEndInput = {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+    operationId: string;
+    actorSubjectId: string;
+};
+export type PrepareBrowserSessionLifecycleInput = PrepareBrowserSessionEndInput;
+export type BrowserPrivateCheckpointAuthority = {
+    artifactId: string;
+    sourceBrowserSessionId: string;
+    objectKey: string;
+    encryptedDataKey: string;
+    format: string;
+    artifactDigest: string;
+    contentDigest: string;
+    manifestDigest: string;
+    sizeBytes: number;
+    materialization: BrowserRevisionMaterializationValue;
+};
+/** Internal executor view of one BrowserSession. Plaintext controller
+ * credentials are deliberately absent; callers derive them from this fenced
+ * durable state. */
+export type BrowserSessionControlRecord = {
+    session: BrowserSession;
+    tokenGeneration: number;
+    sourceSessionId: string;
+    /** Placement hosting browserd. It equals the logical sandbox placement for
+     * managed browsers and remains the source home sandbox for remote browsers. */
+    controllerHostSandboxGroupId: string | null;
+    createOperationId: string;
+    networkRouteAuthority: BrowserSessionNetworkRouteAuthority | null;
+    operation: null | {
+        operationId: string;
+        kind: InteractionLifecycleOperationKind;
+        state: InteractionOperationRow["state"];
+        controllerGeneration: string | null;
+        actorSubjectId: string;
+    };
+};
+export type BrowserSessionNetworkRouteAuthority = {
+    routeId: string;
+    routeVersion: number;
+    credentialVersion: number | null;
+    authorityDigest: string | null;
+    configuration: NetworkRouteConfigurationValue;
+    consistency: NetworkRouteConsistencyValue;
+};
+export declare function browserSessionCreateRequestDigest(input: PrepareBrowserSessionCreateInput): string;
+export declare function listBrowserSessions(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+}): Promise<BrowserSessionListResponseValue>;
+export declare function getBrowserSession(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+}): Promise<{
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    name: string;
+    lifecycle: "active" | "ended" | "ending" | "failed" | "lost" | "repair_required" | "restoring" | "starting" | "suspended" | "suspending";
+    placement: {
+        kind: "sandbox_group";
+        sandboxGroupId: string;
+    } | {
+        kind: "connected_machine";
+        sandboxId: string;
+    } | {
+        kind: "attached_device";
+        deviceId: string;
+    } | {
+        kind: "external_provider";
+        providerId: string;
+        placementId: string;
+    };
+    controller: {
+        controllerId: string;
+        controllerGeneration: string;
+        placementInstanceId: string;
+    } | null;
+    driverId: string;
+    engine: "chrome" | "chromium" | "external" | "firefox" | "lightpanda" | "webkit";
+    engineVersion: string | null;
+    headless: boolean;
+    identityId: string | null;
+    baseRevisionId: string | null;
+    networkRouteId: string | null;
+    linkedComputerSessionId: string | null;
+    capabilities: {
+        semanticObservation: boolean;
+        screenshots: boolean;
+        liveFrames: boolean;
+        humanInput: boolean;
+        tabs: boolean;
+        downloads: boolean;
+        uploads: boolean;
+        clipboard: boolean;
+        permissions: boolean;
+        diagnostics: boolean;
+        rawCdp: boolean;
+        linkedComputer: boolean;
+        privateCheckpoint: boolean;
+        identityPublication: boolean;
+        parallelTargets: boolean;
+    };
+    associations: {
+        sessionId: string;
+        turnId: string | null;
+        attemptId: string | null;
+        relationship: "created" | "observing" | "related" | "using";
+        actorSubjectId: string;
+        lastUsedAt: string;
+    }[];
+    createdBySubjectId: string;
+    createdAt: string;
+    lastUsedAt: string;
+    failureCode: string | null;
+}>;
+export declare function getBrowserSessionControlRecord(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+    operationId?: string;
+}): Promise<BrowserSessionControlRecord>;
+export declare function getBrowserPrivateCheckpointAuthority(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+}): Promise<BrowserPrivateCheckpointAuthority | null>;
+/** Resolve an idempotency key before inspecting mutable placement. This keeps
+ * a retried create bound to its original BrowserSession even if the source
+ * session's active sandbox pointer has since changed. */
+export declare function findBrowserSessionControlRecordByOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+}): Promise<BrowserSessionControlRecord | null>;
+export declare function prepareBrowserSessionCreate(db: Database, input: PrepareBrowserSessionCreateInput): Promise<BrowserSessionMutationResponseValue>;
+/**
+ * Bind the broker-resolved, secret-free launch authority before controller
+ * dispatch. A prepared operation may refresh this binding while no physical
+ * controller owns it; after dispatch it is immutable and replay-fenced.
+ */
+export declare function bindBrowserSessionNetworkRouteAuthority(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+    operationId: string;
+    routeVersion: number;
+    credentialVersion: number | null;
+    authorityDigest: string;
+}): Promise<BrowserSessionNetworkRouteAuthority>;
+export declare function dispatchBrowserSessionOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+    controller?: InteractionControllerBinding;
+    stateUpload?: {
+        objectKey: string;
+        cleanupAfter: Date;
+    };
+}): Promise<InteractionLifecycleOperationReceiptValue>;
+/** Pulse one exact dispatched lifecycle operation while its controller mutation
+ * is still in flight. This is not viewer or resource activity: it exists only
+ * so the global reaper can distinguish a long profile transfer from an API
+ * caller that disappeared after dispatch. */
+export declare function touchInteractionOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    resourceId: string;
+    controllerGeneration: string;
+}): Promise<boolean>;
+export declare function activateBrowserSession(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    controller: InteractionControllerBinding;
+    engineVersion: string | null;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function failBrowserSessionOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    state?: "failed" | "outcome_unknown";
+    error: InteractionErrorValue;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function prepareBrowserSessionSuspend(db: Database, input: PrepareBrowserSessionLifecycleInput): Promise<BrowserSessionMutationResponseValue>;
+export declare function prepareBrowserSessionResume(db: Database, input: PrepareBrowserSessionLifecycleInput): Promise<BrowserSessionMutationResponseValue>;
+export declare function commitBrowserSessionSuspension(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+    artifact: BrowserStateArtifactCommitInput;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function clearSuspendedBrowserSessionController(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+    expectedControllerGeneration: string;
+}): Promise<boolean>;
+export declare function failBrowserSessionSuspension(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+    state?: "failed" | "outcome_unknown";
+    error: InteractionErrorValue;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function failBrowserSessionResume(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+    error: InteractionErrorValue;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function failBrowserSessionResumePreparation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    error: InteractionErrorValue;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function prepareBrowserSessionEnd(db: Database, input: PrepareBrowserSessionEndInput): Promise<BrowserSessionMutationResponseValue>;
+export declare function completeBrowserSessionEnd(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    browserSessionId: string;
+    expectedControllerGeneration: string | null;
+}): Promise<BrowserSessionMutationResponseValue>;
+export declare function touchBrowserSessionController(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+}): Promise<boolean>;
+export {};

package/dist/browser-state-artifacts.d.ts

@@ -0,0 +1,91 @@
+import { type BrowserRevisionMaterialization as BrowserRevisionMaterializationValue } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+import * as schema from "./schema.js";
+type BrowserStateArtifactRow = typeof schema.browserStateArtifacts.$inferSelect;
+type BrowserStateUploadRow = typeof schema.browserStateUploads.$inferSelect;
+export type BrowserStateArtifactCommitInput = {
+    kind: BrowserStateArtifactRow["kind"];
+    format: string;
+    artifactDigest: string;
+    contentDigest: string;
+    manifestDigest: string;
+    objectKey: string;
+    encryptedDataKey: string;
+    sizeBytes: number;
+    materialization: BrowserRevisionMaterializationValue;
+};
+export type BrowserStateArtifactCleanupClaim = {
+    claimId: string;
+    artifactId: string;
+    accountId: string;
+    workspaceId: string;
+    objectKey: string;
+};
+export type BrowserStateUploadPurpose = BrowserStateUploadRow["purpose"];
+export type BrowserStateUploadCleanupClaim = {
+    claimId: string;
+    uploadId: string;
+    accountId: string;
+    workspaceId: string;
+    objectKey: string;
+};
+export declare class BrowserStateUploadStateError extends Error {
+    readonly name = "BrowserStateUploadStateError";
+}
+export type BrowserStateUploadPreparationInput = {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    sourceBrowserSessionId: string;
+    purpose: BrowserStateUploadPurpose;
+    objectKey: string;
+    cleanupAfter: Date;
+};
+/** Validate storage authority before it can become durable state. */
+export declare function validateBrowserStateArtifactCommitInput(workspaceId: string, value: BrowserStateArtifactCommitInput): BrowserStateArtifactCommitInput;
+/** Establish durable cleanup authority before a controller receives a PUT URL. */
+export declare function prepareBrowserStateUpload(db: Database, input: BrowserStateUploadPreparationInput): Promise<{
+    uploadId: string;
+    state: BrowserStateUploadRow["state"];
+}>;
+/** Compose upload authority with operation dispatch in one transaction. */
+export declare function prepareBrowserStateUploadInTransaction(db: Database, input: BrowserStateUploadPreparationInput): Promise<{
+    uploadId: string;
+    state: BrowserStateUploadRow["state"];
+}>;
+/** Queue every uncommitted object owned by a terminal capture operation. */
+export declare function markBrowserStateUploadsDeletePendingInTransaction(db: Database, input: {
+    workspaceId: string;
+    operationId: string;
+}): Promise<void>;
+/** Atomically turn one pre-upload authority into the exact artifact root. */
+export declare function commitBrowserStateUploadInTransaction(db: Database, input: {
+    workspaceId: string;
+    operationId: string;
+    sourceBrowserSessionId: string;
+    purpose: BrowserStateUploadPurpose;
+    objectKey: string;
+    artifactId: string;
+}): Promise<void>;
+/**
+ * Claim a bounded cross-workspace batch of retired private checkpoints. The
+ * privileged SQL function is the only FORCE-RLS bypass; stale claims are
+ * reclaimable and published revision components are structurally ineligible.
+ */
+export declare function claimBrowserStateArtifactCleanup(db: Database, input: {
+    claimTimeoutMs: number;
+    limit: number;
+}): Promise<BrowserStateArtifactCleanupClaim[]>;
+/**
+ * Settle one exact claim only after its provider object was deleted. Completion
+ * is idempotent after a lost response and erases the wrapped data key.
+ */
+export declare function completeBrowserStateArtifactCleanup(db: Database, input: BrowserStateArtifactCleanupClaim): Promise<boolean>;
+/** Claim orphan/failed upload objects after their safety horizon. */
+export declare function claimBrowserStateUploadCleanup(db: Database, input: {
+    claimTimeoutMs: number;
+    limit: number;
+}): Promise<BrowserStateUploadCleanupClaim[]>;
+/** Tombstone one exact orphan upload after its provider object is absent. */
+export declare function completeBrowserStateUploadCleanup(db: Database, input: BrowserStateUploadCleanupClaim): Promise<boolean>;
+export {};

package/dist/canonical-human-identities.d.ts

@@ -0,0 +1,48 @@
+import { type CanonicalHumanIdentityMutationResponse as CanonicalHumanIdentityMutationResponseType, type CanonicalHumanIdentityProjection as CanonicalHumanIdentityProjectionType } from "@opengeni/contracts/canonical-human-identities";
+import type { Database } from "./database.js";
+export type CanonicalHumanSessionAuthority = {
+    identityId: string;
+    identityRevision: number;
+    authRevision: number;
+    identityStatus: "active" | "recovery_required" | "disputed" | "disabled";
+};
+export declare class CanonicalHumanIdentityConflictError extends Error {
+    readonly name = "CanonicalHumanIdentityConflictError";
+    readonly code = "CANONICAL_HUMAN_IDENTITY_CONFLICT";
+    constructor();
+}
+export declare class CanonicalHumanIdentityOperationReuseError extends Error {
+    readonly name = "CanonicalHumanIdentityOperationReuseError";
+    readonly code = "CANONICAL_HUMAN_IDENTITY_OPERATION_REUSED";
+    constructor();
+}
+export declare class CanonicalHumanIdentityNotFoundError extends Error {
+    readonly name = "CanonicalHumanIdentityNotFoundError";
+    constructor(message?: string);
+}
+export declare class CanonicalHumanIdentityAuthorityError extends Error {
+    readonly name = "CanonicalHumanIdentityAuthorityError";
+}
+export declare function ensureCanonicalHumanIdentity(db: Database, input: {
+    authUserId: string;
+    displayName: string;
+}): Promise<CanonicalHumanSessionAuthority>;
+export declare function ensureCanonicalHumanIdentityForAuthUser(db: Database, authUserId: string): Promise<CanonicalHumanSessionAuthority>;
+export declare function synchronizeCanonicalHumanLoginBindings(db: Database, authUserId: string): Promise<CanonicalHumanSessionAuthority>;
+export declare function validateCanonicalHumanSession(db: Database, input: {
+    authSessionId: string;
+    authUserId: string;
+    allowRecovery?: boolean;
+}): Promise<boolean>;
+export declare function getCanonicalHumanIdentityProjection(db: Database, authUserId: string): Promise<CanonicalHumanIdentityProjectionType>;
+export type ApplyCanonicalHumanIdentityOperationInput = {
+    operationId: string;
+    authUserId: string;
+    expectedIdentityRevision: number;
+    operationType: "link" | "unlink" | "begin_recovery" | "recover";
+    bindingId?: string | null;
+    providerId?: string | null;
+    providerAccountId?: string | null;
+    reason: string;
+};
+export declare function applyCanonicalHumanIdentityOperation(db: Database, input: ApplyCanonicalHumanIdentityOperationInput): Promise<CanonicalHumanIdentityMutationResponseType>;

package/dist/canonical-human-identities.js

@@ -0,0 +1,28 @@
+import {
+  CanonicalHumanIdentityAuthorityError,
+  CanonicalHumanIdentityConflictError,
+  CanonicalHumanIdentityNotFoundError,
+  CanonicalHumanIdentityOperationReuseError,
+  applyCanonicalHumanIdentityOperation,
+  ensureCanonicalHumanIdentity,
+  ensureCanonicalHumanIdentityForAuthUser,
+  getCanonicalHumanIdentityProjection,
+  synchronizeCanonicalHumanLoginBindings,
+  validateCanonicalHumanSession
+} from "./chunk-TAUTWOS5.js";
+import "./chunk-JC5QPLUM.js";
+import "./chunk-5KTIEDX7.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  CanonicalHumanIdentityAuthorityError,
+  CanonicalHumanIdentityConflictError,
+  CanonicalHumanIdentityNotFoundError,
+  CanonicalHumanIdentityOperationReuseError,
+  applyCanonicalHumanIdentityOperation,
+  ensureCanonicalHumanIdentity,
+  ensureCanonicalHumanIdentityForAuthUser,
+  getCanonicalHumanIdentityProjection,
+  synchronizeCanonicalHumanLoginBindings,
+  validateCanonicalHumanSession
+};
+//# sourceMappingURL=canonical-human-identities.js.map

package/dist/canonical-human-identities.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/capability-components.d.ts

@@ -0,0 +1,37 @@
+import { sql, type SQLWrapper } from "drizzle-orm";
+import type { Database } from "./database.js";
+export type CapabilityComponentOwnerIdentity = {
+    kind: "direct" | "plugin" | "pack" | "migration";
+    id: string;
+};
+export declare class CapabilityComponentVersionConflictError extends Error {
+    readonly pluginKey: string;
+    readonly name = "CapabilityComponentVersionConflictError";
+    constructor(pluginKey: string);
+}
+/**
+ * An owner row is runtime-effective only while its lifecycle-owning Plugin or
+ * v2 Pack installation is active. Direct, migration, and legacy textual Pack
+ * ownership is intrinsic so the rolling migration does not hide pre-v2 shared
+ * components before those Packs are reinstalled into the normalized ledger.
+ */
+export declare function effectiveCapabilityOwnerSql(ownerKind: SQLWrapper, ownerId: SQLWrapper): ReturnType<typeof sql>;
+/** Serialize one workspace-local component identity across direct, Plugin, and Pack installers. */
+export declare function lockCapabilityComponentIdentity(db: Database, workspaceId: string, pluginKey: string): Promise<void>;
+/**
+ * A child installation selects exactly one immutable Plugin version. Changing
+ * that version is safe only when every retained facet owner is the caller.
+ */
+export declare function assertCapabilityComponentVersionCanChange(db: Database, input: {
+    workspaceId: string;
+    pluginKey: string;
+    pluginInstallationId: string;
+    owner: CapabilityComponentOwnerIdentity;
+}): Promise<void>;
+/**
+ * Delete physically ownerless facet installations and disable now-empty child
+ * components. Inactive lifecycle owners still preserve storage: a Pack may
+ * have claimed a component while its installation is pending or repairing,
+ * even though that owner is intentionally hidden from runtime reads.
+ */
+export declare function cleanupOrphanedCapabilityComponents(db: Database, workspaceId: string, facetInstallationIds: string[]): Promise<void>;