@opengeni/db 1.0.1 → 3.2.0-canary.0

package/dist/connection-authority.d.ts

@@ -0,0 +1,95 @@
+import { ConnectionAuthoritySummary, ConnectionUseAttribution, ConnectionUseAuthorizationResult, type IssueConnectionUseGrantRequest, type ConnectionUseDenialReason as ConnectionUseDenialReasonValue } from "@opengeni/contracts/connection-authority";
+import { type ConnectionKind as ConnectionKindValue, type UserResourceDelegation } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+export declare function listSelfConnectionAuthorities(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+}): Promise<ConnectionAuthoritySummary[]>;
+export declare function issueSelfConnectionUseGrant(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    authorityId: string;
+    request: IssueConnectionUseGrantRequest;
+}): Promise<{
+    grantId: string;
+    targetWorkspaceId: string;
+    targetSessionId: string | null;
+    mode: "always" | "once" | "session";
+    context: "user_private" | "workspace_shared";
+    authorityEpoch: number | null;
+    generation: number;
+    status: "active" | "consumed" | "expired" | "revoked";
+    expiresAt: string | null;
+    delegation: {
+        authorityId: string;
+        grantId: string;
+        organizationId: string;
+        workspaceId: string;
+        sessionId: string | null;
+        action: string;
+        mode: "always" | "once" | "session";
+        context: "user_private" | "workspace_shared";
+        authorityEpoch: number | null;
+        authorityGeneration: number;
+        grantGeneration: number;
+        resourceVersionId?: string | null | undefined;
+    };
+    action: "connection.use";
+}>;
+export declare function revokeSelfConnectionUseGrant(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    grantId: string;
+}): Promise<{
+    grantId: string;
+    generation: number;
+    status: "revoked";
+    revokedAt: string;
+}>;
+/**
+ * Resolves the immutable physical origin for one explicit common-user
+ * connection selection. The SECURITY DEFINER database boundary proves the
+ * owning human, active organization membership, target-workspace access, and
+ * exact authority/grant generations without exposing credentials or allowing
+ * an ambient cross-workspace inventory.
+ */
+export declare function resolvePersonalConnectionAuthoritySelectionOrigin(db: Database, input: {
+    accountId: string;
+    targetWorkspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    delegation: UserResourceDelegation;
+}): Promise<string | null>;
+export declare function resolveConnectionUseAuthority(db: Database, input: {
+    snapshot: unknown;
+}): Promise<ConnectionUseAuthorizationResult>;
+export type AcceptedConnectionUseContext = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+    physicalRequestId: string;
+    usePhase: "credential_resolution" | "provider_request";
+};
+export type AcceptedConnectionUseResolution = {
+    status: "denied";
+    reason: ConnectionUseDenialReasonValue;
+} | {
+    status: "authorized";
+    originWorkspaceId: string;
+    connectionKind: ConnectionKindValue;
+    attribution: ConnectionUseAttribution;
+};
+export declare function resolveAcceptedConnectionUse(db: Database, input: AcceptedConnectionUseContext & {
+    serverId: string;
+    connectionId?: string;
+    providerDomain: string;
+    connectionKind?: ConnectionKindValue;
+    subjectScope?: "workspace" | "subject";
+    ownerSubjectId?: string;
+}): Promise<AcceptedConnectionUseResolution>;

package/dist/connection-scopes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonical comparison key for provider-reported OAuth scopes.
+ *
+ * Google may return the canonical userinfo scope URLs after the application
+ * requested the standard `email` / `profile` aliases. Microsoft scope names
+ * are case-insensitive. All other providers retain exact comparison.
+ */
+export declare function connectionScopeKey(providerDomain: string, value: string): string;

package/dist/connection-tenancy-backfill.d.ts

@@ -0,0 +1,85 @@
+import { type Database } from "./database.js";
+export type ConnectionAuthorityClassificationReport = {
+    schemaVersion: 1;
+    organizationId: string;
+    runKey: string | null;
+    rewroteConnectionRows: false;
+    receiptId?: string;
+    connections: {
+        total: number;
+        workspaceOwned: number;
+        userOwned: number;
+        deterministicRepairPending: number;
+        unresolved: number;
+    };
+};
+export type ConnectionAuthorityBackfillReport = {
+    schemaVersion: 1;
+    organizationId: string;
+    dryRun: boolean;
+    limit: number;
+    candidates: number;
+    upgraded: number;
+    moreLikely: boolean;
+};
+export type ConnectionAuthorityConvergenceClassification = "connection_backfill_ready" | "membership_backfill_eligible" | "membership_lifecycle_review_required" | "external_subject_requires_classification" | "missing_login_identity" | "organization_identity_mismatch" | "missing_owner_workspace_membership" | "conflicting_authority_rows" | "legacy_shape_unrecognized";
+export type ConnectionAuthorityConvergenceAction = "run_connection_backfill" | "run_membership_backfill_then_connection_backfill" | "review_membership_lifecycle_do_not_reactivate_automatically" | "classify_external_subject_then_migrate_via_authorized_connection_lifecycle" | "restore_login_identity_then_recheck" | "correct_organization_identity_through_supported_account_lifecycle_then_recheck" | "establish_owner_workspace_membership_through_supported_membership_lifecycle_then_recheck" | "repair_conflicting_connection_authority_rows_under_incident_procedure" | "repair_unrecognized_connection_authority_shape_under_incident_procedure";
+export type ConnectionAuthorityConvergenceEvidence = {
+    schemaVersion: 1;
+    organizationId: string;
+    limit: number;
+    afterConnectionId: string | null;
+    items: Array<{
+        connectionId: string;
+        subjectId: string | null;
+        classification: ConnectionAuthorityConvergenceClassification;
+        action: ConnectionAuthorityConvergenceAction;
+    }>;
+    returned: number;
+    hasMore: boolean;
+    nextCursor: string | null;
+    /** Full-organization totals. They are deliberately independent of the page cursor. */
+    remaining: {
+        total: number;
+        autoRemediable: number;
+        manualReview: number;
+        byClassification: {
+            connectionBackfillReady: number;
+            membershipBackfillEligible: number;
+            membershipLifecycleReviewRequired: number;
+            externalSubjectRequiresClassification: number;
+            missingLoginIdentity: number;
+            organizationIdentityMismatch: number;
+            missingOwnerWorkspaceMembership: number;
+            conflictingAuthorityRows: number;
+            legacyShapeUnrecognized: number;
+        };
+    };
+};
+/**
+ * Read one bounded evidence page while also returning cursor-independent
+ * full-organization residual totals. The database routine holds a read-only,
+ * invocation-exact FORCE-RLS capability and never writes connection authority.
+ */
+export declare function inspectOrganizationConnectionAuthorityConvergence(db: Database, input: {
+    organizationId: string;
+    limit?: number;
+    afterConnectionId?: string | null;
+}): Promise<ConnectionAuthorityConvergenceEvidence>;
+/**
+ * Full-population connection authority classification. Supplying a fresh run
+ * key writes one immutable migration-0300 receipt and exact unresolved rows.
+ */
+export declare function classifyOrganizationConnectionAuthority(db: Database, input: {
+    organizationId: string;
+    runKey?: string | null;
+}): Promise<ConnectionAuthorityClassificationReport>;
+/**
+ * One bounded, resumable legacy_user -> user upgrade batch. Dry-run is the
+ * default; candidates are claimed with SKIP LOCKED when applying.
+ */
+export declare function backfillOrganizationConnectionAuthority(db: Database, input: {
+    organizationId: string;
+    limit?: number;
+    dryRun?: boolean;
+}): Promise<ConnectionAuthorityBackfillReport>;

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

@@ -1,9 +1,11 @@
 import { environmentsEncryptionKeyBytes, type McpServerConnectionRef, type Settings } from "@opengeni/config";
 import type { ConnectionCredentialPlacement, ConnectionKind, ConnectionCredentialsPort, ConnectionStatus, McpConnectionResourceScope, McpCredentialAuthNeededReason, McpCredentialsRequest, TurnInitiator, TurnInitiatorContext } from "@opengeni/contracts";
+import { type ConnectionUseAttribution, type ConnectionUseAuthorizationResult } from "@opengeni/contracts/connection-authority";
 import { type DnsLookup, type FetchLike } from "@opengeni/network";
 export { isPrivateAddress } from "@opengeni/network";
 import { encryptEnvironmentValue } from "./environment-crypto.js";
 import type { Database } from "./database.js";
+import type { AcceptedConnectionUseContext, AcceptedConnectionUseResolution } from "./connection-authority.js";
 export type ConnectionCredentialForBroker = {
     id: string;
     accountId: string;
@@ -17,6 +19,8 @@ export type ConnectionCredentialForBroker = {
     expiresAt: Date | null;
     lastRefreshAt: Date | null;
     version: number;
+    /** Immutable execution authority generation; distinct from token refresh version. */
+    authorityGeneration?: number;
     metadata: Record<string, unknown>;
 };
 export type ConnectionCredentialLookupInput = {
@@ -26,6 +30,7 @@ export type ConnectionCredentialLookupInput = {
     kind?: ConnectionKind;
     subjectId?: string | null;
     allowSubjectOwned?: boolean;
+    expectedAuthorityGeneration?: number;
 };
 export type ConnectionTokenRefreshInput = {
     id: string;
@@ -34,6 +39,7 @@ export type ConnectionTokenRefreshInput = {
     credentialEncrypted: string;
     expiresAt: Date | null;
     grantedScopes?: string[];
+    metadata?: Record<string, unknown>;
     lastRefreshAt: Date;
     subjectId?: string | null;
 };
@@ -50,6 +56,14 @@ export type ResolveConnectionCredentialResult = {
     connectionId: string;
     /** Exact durable version when the credential came from the local connection store. */
     connectionVersion?: number;
+    /** Metadata-only owner attribution from the immediate pre-use fence. */
+    connectionUseAttribution?: ConnectionUseAttribution;
+    /**
+     * Revalidate the exact accepted attempt immediately before one target
+     * provider request. Credential lookup/refresh is a separate audited
+     * boundary and must not manufacture a provider-request fact by itself.
+     */
+    authorizeProviderRequest?: () => Promise<boolean>;
     expiresAt?: Date | null;
 } | {
     status: "auth_needed";
@@ -75,6 +89,10 @@ export type ResolveConnectionCredentialInput = {
     /** Defaults to header-only MCP transport. */
     credentialTarget?: "mcp" | "http_api";
     forceRefresh?: boolean;
+    /** Exact immutable accepted-work authority; never credential-bearing. */
+    connectionUseAuthority?: unknown;
+    /** Exact accepted attempt plus one stable physical-provider request id. */
+    connectionUseContext?: AcceptedConnectionUseContext;
 };
 export type HostMcpCredentialResolverContext = {
     accountId: string;
@@ -87,7 +105,6 @@ export type HostMcpCredentialResolverContext = {
     initiator: TurnInitiator;
     initiatorContext: TurnInitiatorContext;
     surface: McpCredentialsRequest["surface"];
-    allowOfficialGmailRestDestination?: boolean;
 };
 export declare class HostMcpCredentialScopeError extends Error {
     constructor(field: "accountId" | "workspaceId" | "sessionId");
@@ -111,6 +128,17 @@ export type ConnectionBrokerDeps = {
     encrypt: typeof encryptEnvironmentValue;
     keyBytes: typeof environmentsEncryptionKeyBytes;
     now: () => Date;
+    authorizeUse?: (db: Database, input: {
+        snapshot: unknown;
+    }) => Promise<ConnectionUseAuthorizationResult>;
+    authorizeAcceptedUse?: (db: Database, input: AcceptedConnectionUseContext & {
+        serverId: string;
+        connectionId?: string;
+        providerDomain: string;
+        connectionKind?: ConnectionKind;
+        subjectScope?: "workspace" | "subject";
+        ownerSubjectId?: string;
+    }) => Promise<AcceptedConnectionUseResolution>;
 };
 export type PermanentConnectionRefreshFailure = {
     workspaceId: string;
@@ -152,4 +180,5 @@ export declare function refreshOAuthConnectionCredential(cred: ConnectionCredent
     credential: Record<string, unknown>;
     expiresAt: Date | null;
     grantedScopes?: string[];
+    metadata?: Record<string, unknown>;
 }>;

package/dist/database.d.ts

@@ -57,6 +57,13 @@ export type RlsStrategy = "force" | "scoped";
  * `auth_users` directly. Returns the user id, or null when no such user exists.
  */
 export type UserLookup = (db: Database, email: string) => Promise<string | null>;
+export type ManagedUserProfile = {
+    id: string;
+    name: string | null;
+    email: string;
+};
+/** Host identity projection used by organization administration rosters. */
+export type UserProfileLookup = (db: Database, userIds: readonly string[]) => Promise<ManagedUserProfile[]>;
 export type CreateDbOptions = {
     /**
      * The Postgres `search_path` for this connection (Step I, §7.8 runtime half).
@@ -74,6 +81,8 @@ export type CreateDbOptions = {
     rlsStrategy?: RlsStrategy;
     /** Host-provided user-by-email resolver; unset → today's raw `auth_users` query. */
     userLookup?: UserLookup;
+    /** Host-provided user profile projection; unset → standalone `auth_users`. */
+    userProfileLookup?: UserProfileLookup;
     /** postgres-js pool size; defaults to today's `10`. */
     max?: number;
     /**
@@ -94,6 +103,7 @@ export type CreateDbOptions = {
 type DbBinding = {
     rlsStrategy: RlsStrategy;
     userLookup?: UserLookup;
+    userProfileLookup?: UserProfileLookup;
 };
 /** The strategy bound to a handle (or the `"force"` default). */
 export declare function rlsStrategyFor(db: Database): RlsStrategy;
@@ -144,9 +154,10 @@ export declare function createDb(databaseUrl: string, options?: CreateDbOptions)
 export declare function registerDbBinding(db: Database, binding: {
     rlsStrategy?: RlsStrategy;
     userLookup?: UserLookup;
+    userProfileLookup?: UserProfileLookup;
 }): void;
 export declare function setRlsContext(db: Database, context: RlsContext): Promise<void>;
-export declare function withRlsContext<T>(db: Database, context: RlsContext, fn: (db: Database) => Promise<T>, transactionConfig?: PgTransactionConfig): Promise<T>;
+export declare function withRlsContext<T>(db: Database, context: RlsContext, fn: (db: Database) => Promise<T>, transactionConfig?: PgTransactionConfig, sessionTenancyFence?: "shared" | "none"): Promise<T>;
 /**
  * Run one bounded database operation on a transaction-pinned backend.
  *
@@ -164,8 +175,16 @@ export declare function withWorkspaceRls<T>(db: Database, workspaceId: string, f
  */
 export declare function withSessionActivityRlsContext<T>(db: Database, context: RlsContext & {
     workspaceId: string;
-}, fn: (db: SessionActivityDatabase) => Promise<T>, transactionConfig?: PgTransactionConfig): Promise<T>;
+}, fn: (db: SessionActivityDatabase) => Promise<T>, transactionConfig?: PgTransactionConfig, fenceMode?: "shared" | "none"): Promise<T>;
 export declare function withWorkspaceSessionActivityRls<T>(db: Database, workspaceId: string, fn: (db: SessionActivityDatabase) => Promise<T>, transactionConfig?: PgTransactionConfig): Promise<T>;
+/**
+ * Run one of several ordered workspace activity scopes inside a caller-owned
+ * transaction. Each scope is fully finalized before restoring the caller's
+ * gate GUCs, so the next workspace can reuse the same outer transaction.
+ */
+export declare function withRestoredSessionActivityRlsContext<T>(db: Database, context: RlsContext & {
+    workspaceId: string;
+}, fn: (db: SessionActivityDatabase) => Promise<T>): Promise<T>;
 /**
  * Open one nested savepoint without losing the gate brand. Drizzle correctly
  * preserves the backend-local gate GUCs, but its structural transaction type
@@ -180,8 +199,8 @@ export declare function retryRlsPersistence<T>(db: Database, context: RlsContext
  * `session_pins` uses this helper so FORCE RLS rejects another member's rows
  * even if a future query accidentally omits its explicit subject predicate.
  */
-export declare function withWorkspaceSubjectRls<T>(db: Database, workspaceId: string, subjectId: string, fn: (db: Database) => Promise<T>, transactionConfig?: PgTransactionConfig): Promise<T>;
-export declare function withWorkspaceSubjectSessionActivityRls<T>(db: Database, workspaceId: string, subjectId: string, fn: (db: SessionActivityDatabase) => Promise<T>, transactionConfig?: PgTransactionConfig): Promise<T>;
+export declare function withWorkspaceSubjectRls<T>(db: Database, workspaceId: string, subjectId: string, fn: (db: Database) => Promise<T>, transactionConfig?: PgTransactionConfig, sessionTenancyFence?: "shared" | "none"): Promise<T>;
+export declare function withWorkspaceSubjectSessionActivityRls<T>(db: Database, workspaceId: string, subjectId: string, fn: (db: SessionActivityDatabase) => Promise<T>, transactionConfig?: PgTransactionConfig, fenceMode?: "shared" | "none"): Promise<T>;
 /** Apply and verify actor-private RLS on an already transaction-pinned handle. */
 export declare function setSubjectRlsContext(db: Database, subjectId: string): Promise<void>;
 export declare function withWorkspaceUsageLock<T>(db: Database, workspaceId: string, fn: (db: Database) => Promise<T>): Promise<T>;

package/dist/editable-artifact-durable-export.js

@@ -1,8 +1,8 @@
 import {
   rawRows,
   withRlsContext
-} from "./chunk-ZWREYEWA.js";
-import "./chunk-6ZYKCRFO.js";
+} from "./chunk-AZHW7R5V.js";
+import "./chunk-KRLPEMLH.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/editable-artifact-durable-export.ts

package/dist/editable-artifacts.d.ts

@@ -266,7 +266,7 @@ export type PersistedEditableArtifactLiveHead = (PersistedEditableArtifactLiveBo
     nativeRevision: number;
 }>);
 export type PersistedEditableArtifactLiveResume = Readonly<{
-    modality?: "spreadsheet";
+    modality: "spreadsheet";
     localCursor: number | null;
     localStateHash: string | null;
     localCausalFrontier: PersistedEditableArtifactCausalFrontier;
@@ -286,6 +286,7 @@ export type PersistedEditableArtifactLiveSnapshot = Readonly<{
     causalFrontier: PersistedEditableArtifactCausalFrontier;
     digest: string;
     operationProtocolVersion: number;
+    snapshotVersion: number;
     kernelVersion: string;
     modelSchemaVersion: number;
     bytes: Uint8Array;
@@ -576,7 +577,6 @@ export declare class PostgresEditableArtifactLiveReadStore {
         scope: PersistedEditableArtifactScope;
         artifactId: string;
         resume: PersistedEditableArtifactLiveResume;
-        protocolVersion: number;
     }): Promise<PersistedEditableArtifactLiveBootstrap>;
     readHead(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string): Promise<PersistedEditableArtifactLiveHead>;
     readTransactions(input: {

package/dist/editable-artifacts.js

@@ -8,9 +8,9 @@ import {
   PostgresEditableArtifactStore,
   listEditableArtifactIdsForSession,
   touchEditableArtifactSessionLink
-} from "./chunk-4SR4HKKA.js";
-import "./chunk-ZWREYEWA.js";
-import "./chunk-6ZYKCRFO.js";
+} from "./chunk-2EH4WRHL.js";
+import "./chunk-AZHW7R5V.js";
+import "./chunk-KRLPEMLH.js";
 import "./chunk-PZ5AY32C.js";
 export {
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES,