@sixb/core 0.1.1 → 0.1.2

package/src/connectors/credentials.ts

@@ -0,0 +1,149 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto"
+import { createConnectorCodedError } from "./errors"
+
+export type ConnectorCredentialPurpose = "oauth-authorization" | "pkce-verifier"
+
+/** Immutable identity authenticated alongside one sealed connector credential. */
+export interface ConnectorCredentialContext {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly recordId: string
+  readonly purpose: ConnectorCredentialPurpose
+}
+
+/** Versioned AEAD envelope safe to persist. */
+export interface SealedConnectorCredential {
+  readonly version: 1
+  readonly algorithm: "A256GCM"
+  readonly nonce: string
+  readonly ciphertext: string
+  readonly tag: string
+}
+
+/** Pluggable at-rest protection for connector OAuth credentials and transient PKCE secrets. */
+export interface ConnectorCredentialProtector {
+  seal(
+    plaintext: Uint8Array,
+    context: ConnectorCredentialContext
+  ): Promise<SealedConnectorCredential>
+  open(
+    envelope: SealedConnectorCredential,
+    context: ConnectorCredentialContext
+  ): Promise<Uint8Array>
+}
+
+/** Create credential protection from the base64url key exposed by Sixb configuration. */
+export function createConnectorCredentialProtectorFromKey(
+  encodedKey: string
+): ConnectorCredentialProtector {
+  let key: Buffer
+  try {
+    key = decodeBase64Url(encodedKey)
+  } catch (error) {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      "connectorConnections.encryptionKey must be canonical base64url encoding.",
+      { cause: error }
+    )
+  }
+  if (key.byteLength !== 32) {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      "connectorConnections.encryptionKey must encode exactly 32 random bytes."
+    )
+  }
+  return createAesGcmConnectorCredentialProtector(key)
+}
+
+function createAesGcmConnectorCredentialProtector(
+  encryptionKey: Uint8Array
+): ConnectorCredentialProtector {
+  if (encryptionKey.byteLength !== 32) {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      "Connector credential encryption key must contain exactly 32 bytes."
+    )
+  }
+  const key = Buffer.from(encryptionKey)
+
+  return {
+    async seal(plaintext, context) {
+      assertCredentialContext(context)
+      const nonce = randomBytes(12)
+      const cipher = createCipheriv("aes-256-gcm", key, nonce)
+      cipher.setAAD(credentialAad(context))
+      const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()])
+      return {
+        version: 1,
+        algorithm: "A256GCM",
+        nonce: nonce.toString("base64url"),
+        ciphertext: ciphertext.toString("base64url"),
+        tag: cipher.getAuthTag().toString("base64url"),
+      }
+    },
+    async open(envelope, context) {
+      assertCredentialContext(context)
+      if (envelope.version !== 1 || envelope.algorithm !== "A256GCM") {
+        throw createConnectorCodedError(
+          "connector.credentials_unavailable",
+          "Connector credential envelope format is not supported."
+        )
+      }
+      try {
+        const nonce = decodeBase64Url(envelope.nonce)
+        const ciphertext = decodeBase64Url(envelope.ciphertext)
+        const tag = decodeBase64Url(envelope.tag)
+        if (nonce.byteLength !== 12 || tag.byteLength !== 16) throw new Error("invalid envelope")
+        const decipher = createDecipheriv("aes-256-gcm", key, nonce)
+        decipher.setAAD(credentialAad(context))
+        decipher.setAuthTag(tag)
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()])
+      } catch (error) {
+        throw createConnectorCodedError(
+          "connector.credentials_unavailable",
+          "Connector credential envelope authentication failed.",
+          { cause: error }
+        )
+      }
+    },
+  }
+}
+
+function decodeBase64Url(value: string): Buffer {
+  if (!/^[A-Za-z0-9_-]*$/.test(value)) throw new Error("invalid base64url")
+  const decoded = Buffer.from(value, "base64url")
+  if (decoded.toString("base64url") !== value) throw new Error("non-canonical base64url")
+  return decoded
+}
+
+export function createEphemeralConnectorCredentialProtector(): ConnectorCredentialProtector {
+  return createAesGcmConnectorCredentialProtector(randomBytes(32))
+}
+
+function credentialAad(context: ConnectorCredentialContext): Buffer {
+  return Buffer.from(
+    JSON.stringify({
+      version: 1,
+      projectId: context.projectId,
+      connectorId: context.connectorId,
+      recordId: context.recordId,
+      purpose: context.purpose,
+    })
+  )
+}
+
+function assertCredentialContext(context: ConnectorCredentialContext): void {
+  assertNonblank(context.projectId, "context projectId")
+  assertNonblank(context.connectorId, "context connectorId")
+  assertNonblank(context.recordId, "context recordId")
+}
+
+function assertNonblank(value: string, field: string): string {
+  if (!value.trim()) {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      `Connector credential ${field} must not be empty.`
+    )
+  }
+  return value
+}

package/src/connectors/errors.ts

@@ -1,7 +1,20 @@
+import {
+  createSixbError,
+  isSixbError,
+  type SixbCodedError,
+  type SixbErrorOptions,
+} from "../errors/internal"
+import type { SixbErrorCode } from "../errors/types"
+import { ConnectorConnectionStorageError } from "../storage/connector-connections/errors"
+
+type ConnectorCodedErrorCode = Extract<SixbErrorCode, `connector.${string}`> | "internal.unexpected"
+
 /**
- * Base error for the connectors module. Specific subclasses extend this
- * so callers can catch any connector-scoped failure with a single
- * `instanceof ConnectorError` check.
+ * Legacy authoring error for static connector definitions and lookup.
+ *
+ * Persistent connection lifecycle failures use the global `SixbErrorCode` contract instead.
+ * `ConnectorOAuthError` remains a class because adapters and Core need `instanceof` control flow at
+ * the provider-effect boundary.
  */
 export class ConnectorError extends Error {
   readonly name: string = "ConnectorError"
@@ -13,3 +26,98 @@ export class ConnectorNotFoundError extends ConnectorError {
     super(`Unknown connector '${connectorId}'`)
   }
 }
+
+/**
+ * Provider mutation outcome reported by an OAuth adapter.
+ *
+ * `retryable` guarantees that the provider made no change. `terminal` means the current grant can
+ * no longer progress. `ambiguous` means the provider may have changed state; Core fails closed.
+ * This classifies the provider effect, not the final Sixb error retry policy: Core also accounts for
+ * one-use state, consumed authorization codes, and durable mutation phase before choosing a code.
+ */
+export type ConnectorOAuthErrorKind = "retryable" | "terminal" | "ambiguous"
+
+/** Adapter signal used by Core to decide whether a provider operation can be retried safely. */
+export class ConnectorOAuthError extends ConnectorError {
+  override readonly name = "ConnectorOAuthError"
+
+  constructor(
+    readonly kind: ConnectorOAuthErrorKind,
+    message: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options)
+  }
+}
+
+/** Internal factory for connector failures that cross a Sixb boundary. */
+export function createConnectorCodedError(
+  code: ConnectorCodedErrorCode,
+  message: string,
+  options: SixbErrorOptions = {}
+): SixbCodedError {
+  return createSixbError(
+    code,
+    message.startsWith("[Sixb]") ? message : `[Sixb] ${message}`,
+    options
+  )
+}
+
+/** Internal failure used when a provider operation may have completed after Core lost its fence. */
+export function createAmbiguousProviderOperationError(
+  options: SixbErrorOptions = {}
+): SixbCodedError {
+  return createConnectorCodedError(
+    "connector.provider_failed",
+    "Connector provider operation outcome is ambiguous.",
+    options
+  )
+}
+
+export function oauthErrorKind(error: unknown): ConnectorOAuthErrorKind {
+  return error instanceof ConnectorOAuthError ? error.kind : "ambiguous"
+}
+
+export function providerFailureCode(
+  error: unknown
+): "connector.provider_failed" | "connector.provider_unavailable" {
+  return oauthErrorKind(error) === "retryable"
+    ? "connector.provider_unavailable"
+    : "connector.provider_failed"
+}
+
+export function providerBoundaryError(
+  error: unknown,
+  code: "connector.provider_failed" | "connector.provider_unavailable",
+  message: string
+): Error {
+  if (isSixbError(error) && error.code.startsWith("connector.")) return error
+  return createConnectorCodedError(code, message, { cause: error })
+}
+
+export function isConnectorStorageError(
+  error: unknown,
+  code?: ConnectorConnectionStorageError["code"]
+): error is ConnectorConnectionStorageError {
+  return (
+    error instanceof ConnectorConnectionStorageError && (code === undefined || error.code === code)
+  )
+}
+
+export function storageBoundaryError(error: unknown, message: string): SixbCodedError {
+  return createConnectorCodedError("internal.unexpected", message, { cause: error })
+}
+
+export async function recoverConnectorFailure<T>(
+  primaryError: unknown,
+  message: string,
+  recovery: () => Promise<T>
+): Promise<T> {
+  try {
+    return await recovery()
+  } catch (recoveryError) {
+    throw createConnectorCodedError("internal.unexpected", message, {
+      cause: new AggregateError([primaryError, recoveryError], message),
+    })
+  }
+}

package/src/connectors/execution.ts

@@ -0,0 +1,157 @@
+import { AuthorizationError, assertProviderAccess } from "../authorization"
+import type { ExecutionContext } from "../execution"
+import { resolveExecutionScopeAuthorization } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import { createConnectorCodedError } from "./errors"
+import type { ConnectorService } from "./service"
+import type {
+  AnyConnectorAdapter,
+  ConnectorAdapter,
+  ConnectorClient,
+  ConnectorConnectionMetadata,
+  ConnectorConnectionSelector,
+  ConnectorDefinition,
+  OAuthConnectorAdapter,
+} from "./types"
+import { isOAuthConnectorDefinition } from "./types"
+
+/** Resolve a registered connector through one authorized execution. */
+export interface ConnectorRuntime {
+  <TAdapter extends ConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>
+  ): Promise<ConnectorClient<TAdapter>>
+  <TAdapter extends OAuthConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>,
+    selector: ConnectorConnectionSelector
+  ): Promise<ConnectorClient<TAdapter>>
+}
+
+export interface ConnectorExecutionSource<
+  TAdapter extends AnyConnectorAdapter = AnyConnectorAdapter,
+> {
+  readonly connection?: ConnectorConnectionMetadata
+  connect(signal: AbortSignal): Promise<ConnectorClient<TAdapter>>
+}
+
+export interface ConnectorExecutionSourceResolver {
+  list<TAdapter extends AnyConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>
+  ): Promise<readonly ConnectorExecutionSource<TAdapter>[]>
+}
+
+const sourceResolvers = new WeakMap<ConnectorRuntime, ConnectorExecutionSourceResolver>()
+
+export function createConnectorRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  service: ConnectorService
+): ConnectorRuntime {
+  const connector = ((definition: ConnectorDefinition, selector?: ConnectorConnectionSelector) => {
+    if (isOAuthConnectorDefinition(definition)) {
+      assertConnectorConnectionAccess(runtime, execution)
+      if (!selector) {
+        throw createConnectorCodedError(
+          "connector.configuration_invalid",
+          `[Sixb] Connector '${definition.id}' uses persistent connections and requires an explicit owner and slot.`
+        )
+      }
+      return service.connectConnection(definition, selector)
+    }
+    if (selector) {
+      throw createConnectorCodedError(
+        "connector.configuration_invalid",
+        `[Sixb] Static connector '${definition.id}' does not accept a connection.`
+      )
+    }
+    assertProviderAccess(runtime, execution, "connector.connect")
+    return service.connect(definition as ConnectorDefinition<string, ConnectorAdapter>)
+  }) as ConnectorRuntime
+
+  registerConnectorExecutionSourceResolver(connector, {
+    async list<TAdapter extends AnyConnectorAdapter>(
+      definition: ConnectorDefinition<string, TAdapter>
+    ): Promise<readonly ConnectorExecutionSource<TAdapter>[]> {
+      if (!isOAuthConnectorDefinition(definition)) {
+        return [
+          {
+            connect: (_signal) =>
+              connector(definition as ConnectorDefinition<string, ConnectorAdapter>) as Promise<
+                ConnectorClient<TAdapter>
+              >,
+          },
+        ]
+      }
+
+      assertConnectorConnectionAccess(runtime, execution)
+      const connections = await service.listExecutionConnections(definition)
+      return connections.map((connection) => ({
+        connection: {
+          id: connection.id,
+          connectorId: connection.connectorId,
+          owner: connection.owner,
+          slot: connection.slot,
+          account: connection.account,
+        },
+        connect: (signal) =>
+          service.connectExecutionConnection(definition, connection, signal) as Promise<
+            ConnectorClient<TAdapter>
+          >,
+      }))
+    },
+  })
+  return connector
+}
+
+function registerConnectorExecutionSourceResolver(
+  connector: ConnectorRuntime,
+  resolver: ConnectorExecutionSourceResolver
+): void {
+  const registered = sourceResolvers.get(connector)
+  if (registered && registered !== resolver) {
+    throw new Error("[Sixb] Connector source resolver is already registered for this execution.")
+  }
+  sourceResolvers.set(connector, resolver)
+}
+
+export function getConnectorExecutionSourceResolver(
+  connector: ConnectorRuntime
+): ConnectorExecutionSourceResolver {
+  const resolver = sourceResolvers.get(connector)
+  if (resolver) return resolver
+
+  return {
+    async list<TAdapter extends AnyConnectorAdapter>(
+      definition: ConnectorDefinition<string, TAdapter>
+    ): Promise<readonly ConnectorExecutionSource<TAdapter>[]> {
+      if (isOAuthConnectorDefinition(definition)) {
+        throw createConnectorCodedError(
+          "connector.configuration_invalid",
+          `[Sixb] OAuth connector '${definition.id}' cannot be resolved without the managed connection runtime.`
+        )
+      }
+      return [
+        {
+          connect: (_signal) =>
+            connector(definition as ConnectorDefinition<string, ConnectorAdapter>) as Promise<
+              ConnectorClient<TAdapter>
+            >,
+        },
+      ]
+    },
+  }
+}
+
+function assertConnectorConnectionAccess(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext
+): void {
+  const resolved = resolveExecutionScopeAuthorization(runtime.projectId, {
+    execution,
+    authorization: runtime.runtimeAuthorization,
+  })
+  if (resolved.type === "unrestricted" && resolved.ref.type === "trustedPrimitive") return
+  throw new AuthorizationError(
+    "privileged:connector-connection.connect",
+    "[Sixb] Connector connection clients are restricted to trusted primitive executions."
+  )
+}

package/src/connectors/index.ts

@@ -1,9 +1,33 @@
 export { defineConnector } from "./builders"
-export { ConnectorError, ConnectorNotFoundError } from "./errors"
+export type { ConnectorOAuthErrorKind } from "./errors"
+export { ConnectorError, ConnectorNotFoundError, ConnectorOAuthError } from "./errors"
+export type { ConnectorRuntime } from "./execution"
 export type {
+  AnyConnectorAdapter,
+  ConnectorAccessToken,
+  ConnectorAccountCandidate,
   ConnectorAdapter,
   ConnectorClient,
+  ConnectorConnectionClientContext,
+  ConnectorConnectionMetadata,
+  ConnectorConnectionOptions,
+  ConnectorConnectionOwner,
+  ConnectorConnectionSelector,
   ConnectorContext,
   ConnectorDefinition,
+  ConnectorOAuth2Authentication,
+  ConnectorOAuthCredentials,
+  ConnectorTokenSource,
+  OAuthConnectorAdapter,
+  OAuthConnectorAuthorizationContext,
+  OAuthConnectorAuthorizationUrlInput,
+  OAuthConnectorCodeExchangeInput,
+  ProjectConnectorConnectionOwner,
+  StaticConnectorDefinition,
+} from "./types"
+export {
+  isConnectorDefinition,
+  isOAuthConnectorAdapter,
+  isOAuthConnectorDefinition,
+  isStaticConnectorDefinition,
 } from "./types"
-export { isConnectorDefinition } from "./types"

package/src/connectors/service.ts

@@ -0,0 +1,142 @@
+import type { ConnectorConnectionRecord } from "../storage"
+import type { ConnectorConnectionProcess } from "./connections/contracts"
+import {
+  ConnectorConnectionService,
+  type ConnectorConnectionServiceOptions,
+} from "./connections/service"
+import { ConnectorError, ConnectorNotFoundError, createConnectorCodedError } from "./errors"
+import type {
+  ConnectorAdapter,
+  ConnectorClient,
+  ConnectorConnectionSelector,
+  ConnectorDefinition,
+  OAuthConnectorAdapter,
+} from "./types"
+import { isOAuthConnectorDefinition } from "./types"
+
+export type ConnectorServiceOptions = ConnectorConnectionServiceOptions
+
+type StaticConnectorConnectionState = {
+  readonly controller: AbortController
+  readonly clientPromise: Promise<unknown>
+}
+
+/** Process-owned facade for static clients and persistent connector connections. */
+export class ConnectorService {
+  private readonly definitionsById: ReadonlyMap<string, ConnectorDefinition>
+  private readonly staticConnectionStates = new Map<
+    ConnectorDefinition<string, ConnectorAdapter>,
+    StaticConnectorConnectionState
+  >()
+  private readonly connections?: ConnectorConnectionService
+
+  constructor(
+    private readonly projectId: string,
+    definitions: readonly ConnectorDefinition[],
+    options: ConnectorServiceOptions = {}
+  ) {
+    this.definitionsById = new Map(definitions.map((definition) => [definition.id, definition]))
+    if (definitions.some(isOAuthConnectorDefinition)) {
+      this.connections = new ConnectorConnectionService(projectId, definitions, options)
+    }
+  }
+
+  async connect<TAdapter extends ConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>
+  ): Promise<ConnectorClient<TAdapter>> {
+    this.assertRegistered(definition)
+
+    let state = this.staticConnectionStates.get(definition)
+    if (!state) {
+      const controller = new AbortController()
+      const clientPromise = Promise.resolve(
+        definition.adapter.connect({
+          projectId: this.projectId,
+          connectorId: definition.id,
+          signal: controller.signal,
+        })
+      )
+      state = { controller, clientPromise }
+      this.staticConnectionStates.set(definition, state)
+    }
+
+    try {
+      return (await state.clientPromise) as ConnectorClient<TAdapter>
+    } catch (error) {
+      if (this.staticConnectionStates.get(definition) === state) {
+        this.staticConnectionStates.delete(definition)
+      }
+      throw error
+    }
+  }
+
+  connectConnection<TAdapter extends OAuthConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>,
+    selector: ConnectorConnectionSelector
+  ): Promise<ConnectorClient<TAdapter>> {
+    return this.requireConnections().connectConnection(definition, selector)
+  }
+
+  listExecutionConnections<TAdapter extends OAuthConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>
+  ): Promise<readonly ConnectorConnectionRecord[]> {
+    return this.requireConnections().listExecutionConnections(definition)
+  }
+
+  connectExecutionConnection<TAdapter extends OAuthConnectorAdapter>(
+    definition: ConnectorDefinition<string, TAdapter>,
+    connection: ConnectorConnectionRecord,
+    signal?: AbortSignal
+  ): Promise<ConnectorClient<TAdapter>> {
+    return this.requireConnections().connectExecutionConnection(definition, connection, signal)
+  }
+
+  get connectionProcess(): ConnectorConnectionProcess | undefined {
+    return this.connections
+  }
+
+  async close(): Promise<void> {
+    await this.connections?.close()
+    const activeConnections = [...this.staticConnectionStates.entries()]
+    this.staticConnectionStates.clear()
+    for (const [definition, state] of activeConnections) {
+      await this.disconnectStaticState(definition, state)
+    }
+  }
+
+  private assertRegistered(definition: ConnectorDefinition): void {
+    const registeredDefinition = this.definitionsById.get(definition.id)
+    if (!registeredDefinition) throw new ConnectorNotFoundError(definition.id)
+    if (registeredDefinition !== definition) {
+      throw new ConnectorError(
+        `Connector '${definition.id}' is not the registered definition instance.`
+      )
+    }
+  }
+
+  private requireConnections(): ConnectorConnectionService {
+    if (!this.connections) {
+      throw createConnectorCodedError(
+        "connector.configuration_invalid",
+        "No OAuth connectors are registered with this runtime."
+      )
+    }
+    return this.connections
+  }
+
+  private async disconnectStaticState(
+    definition: ConnectorDefinition<string, ConnectorAdapter>,
+    state: StaticConnectorConnectionState
+  ): Promise<void> {
+    state.controller.abort()
+    let client: unknown
+    try {
+      client = await state.clientPromise
+    } catch {
+      return
+    }
+    if (typeof definition.adapter.disconnect === "function") {
+      await definition.adapter.disconnect(client as never)
+    }
+  }
+}