@sixb/core 0.1.1 → 0.1.2

package/src/storage/connector-connections/types.ts

@@ -0,0 +1,546 @@
+import type { ConnectorAccountCandidate, ConnectorConnectionSelector } from "../../connectors"
+import type { SealedConnectorCredential } from "../../connectors/credentials"
+import type { SixbErrorCode, SixbFailure } from "../../errors/types"
+import type { AuthorizablePrincipal } from "../../execution"
+
+export type {
+  ConnectorConnectionOwner,
+  ConnectorConnectionSelector,
+  ProjectConnectorConnectionOwner,
+} from "../../connectors"
+
+export const CONNECTOR_CONNECTION_RUN_FAILURE_CODES = [
+  "internal.unexpected",
+  "connector.adapter_invalid",
+  "connector.authorization_invalid",
+  "connector.authorization_required",
+  "connector.credentials_unavailable",
+  "connector.not_found",
+  "connector.operation_conflict",
+  "connector.operation_in_progress",
+  "connector.provider_failed",
+  "connector.provider_unavailable",
+] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
+
+export type ConnectorConnectionRunFailureCode =
+  (typeof CONNECTOR_CONNECTION_RUN_FAILURE_CODES)[number]
+export type ConnectorConnectionRunFailure = SixbFailure<ConnectorConnectionRunFailureCode>
+export type ConnectorConnectionRunKind = "connect" | "reauthorize"
+
+interface ConnectorConnectionRunBase extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly kind: ConnectorConnectionRunKind
+  /** Durable request execution that initiated and is allowed to manage this run. */
+  readonly initiatedByExecutionId: string
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+
+export interface ConnectorConnectionRunAwaitingProviderRecord extends ConnectorConnectionRunBase {
+  readonly status: "waiting"
+  readonly waitingFor: "provider_authorization"
+  readonly expiresAt: Date
+}
+
+export interface ConnectorConnectionRunProcessingRecord extends ConnectorConnectionRunBase {
+  readonly status: "running"
+  /** Fences every callback-side write after the one-shot OAuth attempt was consumed. */
+  readonly processingId: string
+  readonly callbackStartedAt: Date
+  readonly expiresAt: Date
+  /** Internal grant handle, attached as soon as a new authorization is durably persisted. */
+  readonly authorizationId?: string
+}
+
+export interface ConnectorConnectionRunAwaitingSelectionRecord extends ConnectorConnectionRunBase {
+  readonly status: "waiting"
+  readonly waitingFor: "account_selection"
+  readonly authorizationId: string
+  readonly expiresAt: Date
+}
+
+export interface ConnectorConnectionRunSucceededRecord extends ConnectorConnectionRunBase {
+  readonly status: "succeeded"
+  readonly authorizationId: string
+  /** Internal handle for a replaced grant whose provider cleanup is still retryable. */
+  readonly cleanupAuthorizationId?: string
+  readonly connections: readonly ConnectorConnectionRecord[]
+  readonly finishedAt: Date
+}
+
+export interface ConnectorConnectionRunFailedRecord extends ConnectorConnectionRunBase {
+  readonly status: "failed"
+  readonly error: ConnectorConnectionRunFailure
+  /** Internal cleanup handle; never serialized by the Headless API. */
+  readonly authorizationId?: string
+  readonly finishedAt: Date
+}
+
+export interface ConnectorConnectionRunCancelledRecord extends ConnectorConnectionRunBase {
+  readonly status: "cancelled"
+  readonly authorizationId?: string
+  readonly finishedAt: Date
+}
+
+export interface ConnectorConnectionRunExpiredRecord extends ConnectorConnectionRunBase {
+  readonly status: "expired"
+  readonly authorizationId?: string
+  readonly finishedAt: Date
+}
+
+export type ConnectorConnectionRunRecord =
+  | ConnectorConnectionRunAwaitingProviderRecord
+  | ConnectorConnectionRunProcessingRecord
+  | ConnectorConnectionRunAwaitingSelectionRecord
+  | ConnectorConnectionRunSucceededRecord
+  | ConnectorConnectionRunFailedRecord
+  | ConnectorConnectionRunCancelledRecord
+  | ConnectorConnectionRunExpiredRecord
+
+export interface CreateConnectorConnectionRunInput extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly kind: ConnectorConnectionRunKind
+  readonly initiatedByExecutionId: string
+  readonly ttlMs: number
+}
+
+export interface CreateConnectorConnectionSelectionRunInput extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly initiatedByExecutionId: string
+  readonly authorizationId: string
+  readonly ttlMs: number
+}
+
+export interface ClaimConnectorConnectionRunCallbackInput {
+  readonly projectId: string
+  readonly attemptId: string
+  readonly stateHash: string
+  readonly callbackBindingHash: string
+  readonly redirectUri: string
+  readonly processingId: string
+  readonly processingTtlMs: number
+}
+
+export type ClaimConnectorConnectionRunCallbackResult =
+  | {
+      readonly type: "claimed"
+      readonly run: ConnectorConnectionRunProcessingRecord
+      readonly attempt: ConnectorAuthorizationAttemptRecord
+      readonly returnTo: string
+    }
+  | {
+      readonly type: "expired"
+      readonly run: ConnectorConnectionRunExpiredRecord
+      readonly returnTo: string
+    }
+
+export interface WaitForConnectorConnectionRunSelectionInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly runId: string
+  readonly processingId: string
+  readonly authorizationId: string
+  readonly expiresAt: Date
+}
+
+export interface AttachConnectorConnectionRunAuthorizationInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly runId: string
+  readonly processingId: string
+  readonly authorizationId: string
+}
+
+export type FinishConnectorConnectionRunInput =
+  | {
+      readonly projectId: string
+      readonly connectorId: string
+      readonly runId: string
+      readonly processingId: string
+      readonly status: "succeeded"
+      readonly authorizationId: string
+      readonly cleanupAuthorizationId?: string
+      readonly connections: readonly ConnectorConnectionRecord[]
+    }
+  | {
+      readonly projectId: string
+      readonly connectorId: string
+      readonly runId: string
+      readonly processingId: string
+      readonly status: "failed"
+      readonly error: ConnectorConnectionRunFailure
+      readonly authorizationId?: string
+    }
+  | {
+      readonly projectId: string
+      readonly connectorId: string
+      readonly runId: string
+      readonly processingId: string
+      readonly status: "cancelled"
+    }
+
+export interface GetConnectorConnectionRunInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly runId: string
+}
+
+export interface ConnectorAuthorizationAttemptRecord extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  /** Durable execution that initiated and authorizes completion of this OAuth attempt. */
+  readonly initiatedByExecutionId: string
+  readonly stateHash: string
+  readonly codeVerifier: SealedConnectorCredential
+  readonly redirectUri: string
+  /** Present only for attempts created by the headless connection-run API. */
+  readonly connectionRunId?: string
+  /** Fixed, allowlisted continuation consumed with a headless callback. */
+  readonly returnTo?: string
+  /** Hash of the one-shot browser callback binding secret. */
+  readonly callbackBindingHash?: string
+  readonly reauthorizationId?: string
+  readonly reauthorizationRevision?: number
+  readonly reauthorizationConnectionIds?: readonly string[]
+  readonly createdAt: Date
+  readonly expiresAt: Date
+}
+
+export interface CreateConnectorAuthorizationAttemptInput extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly initiatedByExecutionId: string
+  readonly stateHash: string
+  readonly codeVerifier: SealedConnectorCredential
+  readonly redirectUri: string
+  readonly connectionRunId?: string
+  readonly returnTo?: string
+  readonly callbackBindingHash?: string
+  readonly reauthorizationId?: string
+  readonly reauthorizationRevision?: number
+  readonly reauthorizationConnectionIds?: readonly string[]
+  readonly ttlMs: number
+}
+
+/** Callback proof. The orchestration layer authorizes the returned initiating execution. */
+export interface ConsumeConnectorAuthorizationAttemptInput {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly stateHash: string
+  readonly redirectUri: string
+}
+
+export type ConnectorAuthorizationStatus =
+  | "pending_selection"
+  | "active"
+  | "needs_reauthorization"
+  | "revocation_pending"
+  | "revoked"
+
+export type ConnectorCredentialMutationKind = "refresh" | "reauthorization" | "revocation"
+export type ConnectorCredentialMutationPhase = "prepared" | "executing" | "result_staged"
+
+export interface ConnectorStagedCredentials {
+  readonly credentials: SealedConnectorCredential
+  readonly credentialExpiresAt?: Date
+  readonly scopes: readonly string[]
+}
+
+/** Durable fencing record for one provider-side OAuth credential mutation. */
+export interface ConnectorCredentialMutation {
+  readonly id: string
+  readonly kind: ConnectorCredentialMutationKind
+  readonly phase: ConnectorCredentialMutationPhase
+  readonly holderId: string
+  readonly expiresAt: Date
+  readonly deadlineAt: Date
+  readonly expectedConnectionIds?: readonly string[]
+  readonly stagedCredentials?: ConnectorStagedCredentials
+}
+
+export interface ConnectorAuthorizationRecord {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizedBy: AuthorizablePrincipal
+  /** Removed after provider revocation is confirmed. */
+  readonly credentials?: SealedConnectorCredential
+  readonly credentialExpiresAt?: Date
+  readonly scopes: readonly string[]
+  readonly accounts: readonly ConnectorAccountCandidate[]
+  readonly status: ConnectorAuthorizationStatus
+  /** Storage-authoritative deadline for the first account selection. */
+  readonly selectionExpiresAt?: Date
+  readonly revision: number
+  readonly credentialMutation?: ConnectorCredentialMutation
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+
+export interface CreateConnectorAuthorizationInput {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizedBy: AuthorizablePrincipal
+  readonly credentials: SealedConnectorCredential
+  readonly credentialExpiresAt?: Date
+  readonly scopes: readonly string[]
+  readonly accounts: readonly ConnectorAccountCandidate[]
+  readonly selectionTtlMs: number
+}
+
+export interface InitializeConnectorAuthorizationAccountsInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+  readonly expectedRevision: number
+  readonly accounts: readonly ConnectorAccountCandidate[]
+}
+
+export interface ClaimConnectorCredentialMutationInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+  readonly expectedRevision: number
+  readonly mutation: {
+    readonly id: string
+    readonly kind: ConnectorCredentialMutationKind
+    readonly holderId: string
+  }
+  readonly expectedConnectionIds?: readonly string[]
+  readonly leaseDurationMs: number
+  readonly operationTimeoutMs: number
+}
+
+export interface ClaimConnectorCredentialMutationResult {
+  readonly authorization: ConnectorAuthorizationRecord
+  readonly disconnected: readonly ConnectorConnectionRecord[]
+}
+
+export interface ConnectorCredentialMutationFence {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+  readonly expectedRevision: number
+  readonly mutationId: string
+}
+
+export interface MarkConnectorCredentialMutationExecutingInput
+  extends ConnectorCredentialMutationFence {
+  readonly holderId: string
+}
+
+export interface RenewConnectorCredentialMutationInput extends ConnectorCredentialMutationFence {
+  readonly holderId: string
+  readonly leaseDurationMs: number
+}
+
+export interface StageConnectorCredentialMutationCredentialsInput
+  extends ConnectorCredentialMutationFence {
+  readonly holderId: string
+  readonly credentials: SealedConnectorCredential
+  readonly credentialExpiresAt?: Date
+  readonly scopes: readonly string[]
+}
+
+export interface StageConnectorCredentialMutationRevocationInput
+  extends ConnectorCredentialMutationFence {
+  readonly holderId: string
+}
+
+export interface ReleaseConnectorCredentialMutationInput extends ConnectorCredentialMutationFence {
+  readonly holderId: string
+}
+
+export interface RecoverExpiredConnectorCredentialMutationInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+}
+
+export interface MarkConnectorAuthorizationNeedsReauthorizationInput
+  extends ConnectorCredentialMutationFence {}
+
+export interface FinalizeConnectorReauthorizationInput extends ConnectorCredentialMutationFence {
+  readonly accounts: readonly ConnectorAccountCandidate[]
+}
+
+export type ConnectorConnectionStatus = "connected" | "disconnected"
+
+export interface ConnectorConnectionRecord extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+  readonly account: ConnectorAccountCandidate
+  readonly status: ConnectorConnectionStatus
+  readonly disconnectedAt?: Date
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+
+export interface PutConnectorConnectionInput extends ConnectorConnectionSelector {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+  readonly account: ConnectorAccountCandidate
+  readonly replace: boolean
+}
+
+export interface PutConnectorConnectionResult {
+  readonly connection: ConnectorConnectionRecord
+  readonly authorization: ConnectorAuthorizationRecord
+  readonly revocationPendingAuthorizationId?: string
+  readonly created: boolean
+  readonly replaced: boolean
+}
+
+export interface DisconnectConnectorConnectionResult {
+  readonly connection: ConnectorConnectionRecord
+  readonly authorization: ConnectorAuthorizationRecord
+  readonly revocationPendingAuthorizationId?: string
+}
+
+export interface PutConnectorConnectionFromRunInput {
+  readonly id: string
+  readonly projectId: string
+  readonly connectorId: string
+  readonly runId: string
+  readonly account: ConnectorAccountCandidate
+  readonly replace: boolean
+}
+
+export interface PutConnectorConnectionFromRunResult extends PutConnectorConnectionResult {
+  readonly run: ConnectorConnectionRunSucceededRecord
+}
+
+export interface GetConnectorConnectionInput extends ConnectorConnectionSelector {
+  readonly projectId: string
+  readonly connectorId: string
+}
+
+export interface ListConnectorConnectionsInput {
+  readonly projectId: string
+  readonly connectorId: string
+}
+
+/** Tenant-scoped identity for one connector authorization. */
+export interface ConnectorAuthorizationKey {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly authorizationId: string
+}
+
+/** Tenant-scoped identity for one selected connector connection. */
+export interface ConnectorConnectionKey {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly connectionId: string
+}
+
+/** Persistent contract. Implementations must make every individual mutation atomic. */
+export interface ConnectorConnectionStorage {
+  readonly durability: "ephemeral" | "durable"
+
+  createAuthorizationAttempt(
+    input: CreateConnectorAuthorizationAttemptInput
+  ): Promise<ConnectorAuthorizationAttemptRecord>
+  consumeAuthorizationAttempt(
+    input: ConsumeConnectorAuthorizationAttemptInput
+  ): Promise<ConnectorAuthorizationAttemptRecord>
+
+  createConnectionRun(
+    input: CreateConnectorConnectionRunInput
+  ): Promise<ConnectorConnectionRunRecord>
+  createConnectionSelectionRun(
+    input: CreateConnectorConnectionSelectionRunInput
+  ): Promise<ConnectorConnectionRunAwaitingSelectionRecord>
+  claimConnectionRunCallback(
+    input: ClaimConnectorConnectionRunCallbackInput
+  ): Promise<ClaimConnectorConnectionRunCallbackResult | null>
+  attachConnectionRunAuthorization(
+    input: AttachConnectorConnectionRunAuthorizationInput
+  ): Promise<ConnectorConnectionRunProcessingRecord | null>
+  waitForConnectionRunSelection(
+    input: WaitForConnectorConnectionRunSelectionInput
+  ): Promise<ConnectorConnectionRunAwaitingSelectionRecord | null>
+  finishConnectionRun(
+    input: FinishConnectorConnectionRunInput
+  ): Promise<ConnectorConnectionRunRecord | null>
+  getConnectionRun(
+    input: GetConnectorConnectionRunInput
+  ): Promise<ConnectorConnectionRunRecord | null>
+
+  createAuthorization(
+    input: CreateConnectorAuthorizationInput
+  ): Promise<ConnectorAuthorizationRecord>
+  initializeAuthorizationAccounts(
+    input: InitializeConnectorAuthorizationAccountsInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  getAuthorization(input: ConnectorAuthorizationKey): Promise<ConnectorAuthorizationRecord | null>
+  getAuthorizationByConnectionId(
+    input: ConnectorConnectionKey
+  ): Promise<ConnectorAuthorizationRecord | null>
+  claimCredentialMutation(
+    input: ClaimConnectorCredentialMutationInput
+  ): Promise<ClaimConnectorCredentialMutationResult | null>
+  markCredentialMutationExecuting(
+    input: MarkConnectorCredentialMutationExecutingInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  renewCredentialMutation(
+    input: RenewConnectorCredentialMutationInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  stageCredentialMutationCredentials(
+    input: StageConnectorCredentialMutationCredentialsInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  stageCredentialMutationRevocation(
+    input: StageConnectorCredentialMutationRevocationInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  releaseCredentialMutation(input: ReleaseConnectorCredentialMutationInput): Promise<boolean>
+  /**
+   * Recovers an expired mutation without replaying an unknown provider effect. Prepared work is
+   * released, executing refresh/reauthorization fails closed, revocation stays retryable, and a
+   * staged result remains available for finalization.
+   */
+  recoverExpiredCredentialMutation(
+    input: RecoverExpiredConnectorCredentialMutationInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  markNeedsReauthorization(
+    input: MarkConnectorAuthorizationNeedsReauthorizationInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  finalizeRefresh(
+    input: ConnectorCredentialMutationFence
+  ): Promise<ConnectorAuthorizationRecord | null>
+  finalizeReauthorization(
+    input: FinalizeConnectorReauthorizationInput
+  ): Promise<ConnectorAuthorizationRecord | null>
+  finalizeRevocation(
+    input: ConnectorCredentialMutationFence
+  ): Promise<ConnectorAuthorizationRecord | null>
+
+  putConnection(input: PutConnectorConnectionInput): Promise<PutConnectorConnectionResult>
+  putConnectionFromRun(
+    input: PutConnectorConnectionFromRunInput
+  ): Promise<PutConnectorConnectionFromRunResult>
+  getConnection(input: GetConnectorConnectionInput): Promise<ConnectorConnectionRecord | null>
+  getConnectionById(input: ConnectorConnectionKey): Promise<ConnectorConnectionRecord | null>
+  listConnections(
+    input: ListConnectorConnectionsInput
+  ): Promise<readonly ConnectorConnectionRecord[]>
+  listConnectionsByAuthorization(
+    input: ConnectorAuthorizationKey
+  ): Promise<readonly ConnectorConnectionRecord[]>
+  disconnectConnection(
+    input: ConnectorConnectionKey
+  ): Promise<DisconnectConnectorConnectionResult | null>
+}

package/src/storage/executions/errors.ts

@@ -0,0 +1,21 @@
+export type ExecutionStorageErrorCode =
+  | "duplicate_execution"
+  | "invalid_credential"
+  | "invalid_input"
+  | "invalid_parent_execution"
+  | "missing_credential"
+  | "missing_parent_execution"
+  | "missing_principal"
+
+/** Stable error raised when an execution record would violate ledger invariants. */
+export class ExecutionStorageError extends Error {
+  readonly name = "ExecutionStorageError"
+
+  constructor(
+    readonly code: ExecutionStorageErrorCode,
+    message: string,
+    options: ErrorOptions = {}
+  ) {
+    super(message, options)
+  }
+}

package/src/storage/executions/in-memory.ts

@@ -0,0 +1,75 @@
+import type { AuthStorage } from "../auth"
+import { ExecutionStorageError } from "./errors"
+import type { CreateExecutionInput, ExecutionRecord, ExecutionStorage } from "./types"
+import {
+  cloneExecutionRecord,
+  normalizeExecutionRecord,
+  validateExecutionRecordReferences,
+} from "./validation"
+
+type RunRootOperation = <T>(run: () => Promise<T> | T) => Promise<T>
+
+const runDirectly: RunRootOperation = async <T>(run: () => Promise<T> | T): Promise<T> => run()
+
+function executionKey(projectId: string, id: string): string {
+  return JSON.stringify([projectId, id])
+}
+
+export class InMemoryExecutionStorage implements ExecutionStorage {
+  private readonly rows = new Map<string, ExecutionRecord>()
+  private readonly runRootOperation: RunRootOperation
+
+  constructor(
+    private readonly auth: AuthStorage,
+    input: { readonly runRootOperation?: RunRootOperation } = {}
+  ) {
+    this.runRootOperation = input.runRootOperation ?? runDirectly
+  }
+
+  snapshot(): InMemoryExecutionStorageSnapshot {
+    return structuredClone(this.rows)
+  }
+
+  restore(snapshot: InMemoryExecutionStorageSnapshot): void {
+    this.rows.clear()
+    for (const [key, record] of structuredClone(snapshot)) {
+      this.rows.set(key, record)
+    }
+  }
+
+  async create(input: CreateExecutionInput): Promise<ExecutionRecord> {
+    return this.runRootOperation(async () => {
+      const record = normalizeExecutionRecord(input)
+      const key = executionKey(record.projectId, record.id)
+      if (this.rows.has(key)) {
+        throw new ExecutionStorageError(
+          "duplicate_execution",
+          `[Sixb] Execution '${record.id}' already exists in project '${record.projectId}'.`
+        )
+      }
+
+      await validateExecutionRecordReferences(record, {
+        auth: this.auth,
+        getExecution: async ({ projectId, id }) => {
+          const existing = this.rows.get(executionKey(projectId, id))
+          return existing ? cloneExecutionRecord(existing) : null
+        },
+      })
+
+      this.rows.set(key, cloneExecutionRecord(record))
+      return cloneExecutionRecord(record)
+    })
+  }
+
+  async getById(params: {
+    readonly projectId: string
+    readonly id: string
+  }): Promise<ExecutionRecord | null> {
+    return this.runRootOperation(() => {
+      const record = this.rows.get(executionKey(params.projectId, params.id))
+      return record ? cloneExecutionRecord(record) : null
+    })
+  }
+}
+
+export type InMemoryExecutionStorageSnapshot = Map<string, ExecutionRecord>

package/src/storage/executions/index.ts

@@ -0,0 +1,16 @@
+export type {
+  AuthorizablePrincipal,
+  AuthorizationRef,
+  KernelOperation,
+  TrustedPrimitiveKind,
+  TrustedPrimitiveRef,
+} from "../../execution/types"
+export type { ExecutionStorageErrorCode } from "./errors"
+export { ExecutionStorageError } from "./errors"
+export type {
+  CreateExecutionInput,
+  DurableExecutionExecutor,
+  DurableExecutionSource,
+  ExecutionRecord,
+  ExecutionStorage,
+} from "./types"