@sixb/core 0.1.1 → 0.1.2

package/src/connectors/connections/tokens.ts

@@ -0,0 +1,292 @@
+import type { ConnectorAuthorizationRecord, ConnectorConnectionStorage } from "../../storage"
+import { createConnectorCodedError, oauthErrorKind, recoverConnectorFailure } from "../errors"
+import type {
+  ConnectorAccessToken,
+  ConnectorDefinition,
+  ConnectorOAuthCredentials,
+  ConnectorTokenSource,
+  OAuthConnectorAdapter,
+} from "../types"
+import type { ConnectorCredentialCodec } from "./credential-codec"
+import {
+  assertCredentialMutationOperationActive,
+  type ConnectorCredentialMutationCoordinator,
+  connectorAuthorizationStatusError,
+} from "./credential-mutations"
+import { withConnectorStorageBoundary } from "./storage-boundary"
+import { nonNegativeDuration, shouldRefresh, tokenView, validateCredentials } from "./validation"
+
+type OAuthConnectorDefinition = ConnectorDefinition<string, OAuthConnectorAdapter>
+
+export interface ConnectorTokenAccessOptions {
+  readonly projectId: string
+  readonly storage: ConnectorConnectionStorage
+  readonly credentials: ConnectorCredentialCodec
+  readonly mutations: ConnectorCredentialMutationCoordinator
+  readonly refreshSkewMs: number
+  readonly now: () => Date
+}
+
+/** Owns revision-aware access-token delivery and refresh. */
+export class ConnectorTokenAccess {
+  private readonly projectId: string
+  private readonly storage: ConnectorConnectionStorage
+  private readonly credentials: ConnectorCredentialCodec
+  private readonly mutations: ConnectorCredentialMutationCoordinator
+  private readonly refreshSkewMs: number
+  private readonly now: () => Date
+
+  constructor(options: ConnectorTokenAccessOptions) {
+    this.projectId = options.projectId
+    this.storage = options.storage
+    this.credentials = options.credentials
+    this.mutations = options.mutations
+    this.refreshSkewMs = nonNegativeDuration(options.refreshSkewMs, "refresh skew")
+    this.now = options.now
+  }
+
+  requireStableActiveAuthorization(
+    definition: OAuthConnectorDefinition,
+    authorizationId: string
+  ): Promise<ConnectorAuthorizationRecord> {
+    return this.mutations.requireStableActiveAuthorization(definition.id, authorizationId)
+  }
+
+  createTokenSource(
+    definition: OAuthConnectorDefinition,
+    authorizationId: string
+  ): ConnectorTokenSource {
+    return new RevisionAwareConnectorTokenSource((rejectedRevision) =>
+      this.getAccessToken(definition, authorizationId, rejectedRevision)
+    )
+  }
+
+  private open(
+    connectorId: string,
+    authorization: ConnectorAuthorizationRecord
+  ): Promise<ConnectorOAuthCredentials> {
+    if (!authorization.credentials) {
+      throw createConnectorCodedError(
+        "connector.credentials_unavailable",
+        "Stored connector credentials are unavailable."
+      )
+    }
+    return this.credentials.open(connectorId, authorization.id, authorization.credentials)
+  }
+
+  private async getAccessToken(
+    definition: OAuthConnectorDefinition,
+    authorizationId: string,
+    rejectedRevision?: number
+  ): Promise<{
+    readonly token: { readonly accessToken: string; readonly tokenType?: string }
+    readonly revision: number
+  }> {
+    let authorization = await this.mutations.requireStableActiveAuthorization(
+      definition.id,
+      authorizationId
+    )
+    const credentials = await this.open(definition.id, authorization)
+    const refreshRejectedToken =
+      rejectedRevision !== undefined && rejectedRevision === authorization.revision
+    if (refreshRejectedToken || shouldRefresh(authorization, this.now(), this.refreshSkewMs)) {
+      authorization = await this.refreshAuthorization(definition, authorization)
+      const refreshed = await this.open(definition.id, authorization)
+      return { token: tokenView(refreshed), revision: authorization.revision }
+    }
+    return { token: tokenView(credentials), revision: authorization.revision }
+  }
+
+  private async refreshAuthorization(
+    definition: OAuthConnectorDefinition,
+    initial: ConnectorAuthorizationRecord
+  ): Promise<ConnectorAuthorizationRecord> {
+    return this.mutations.runLocallySerialized(initial.id, async () => {
+      let authorization = await this.mutations.requireStableActiveAuthorization(
+        definition.id,
+        initial.id
+      )
+      if (authorization.revision !== initial.revision) return authorization
+      authorization = await this.mutations.prepareAuthorizationForMutation(
+        definition.id,
+        authorization,
+        "refresh"
+      )
+      if (authorization.revision !== initial.revision) return authorization
+      const claimOutcome = await this.mutations.claimCredentialMutation(
+        definition.id,
+        authorization,
+        "refresh"
+      )
+      if (claimOutcome.type === "superseded") return claimOutcome.authorization
+      const { claim } = claimOutcome
+
+      let current: ConnectorOAuthCredentials
+      try {
+        current = await this.open(definition.id, claim.authorization)
+      } catch (error) {
+        await recoverConnectorFailure(
+          error,
+          "Connector credential mutation could not be released after credential decryption failed.",
+          () => this.mutations.releaseCredentialMutation(claim.authorization)
+        )
+        throw createConnectorCodedError(
+          "connector.credentials_unavailable",
+          "Stored connector credentials could not be opened.",
+          { cause: error }
+        )
+      }
+      if (!current.refreshToken) {
+        const error = createConnectorCodedError(
+          "connector.authorization_required",
+          "Connector credentials require reauthorization."
+        )
+        await recoverConnectorFailure(
+          error,
+          "Connector authorization could not be marked for reauthorization after finding no refresh token.",
+          () => this.mutations.markNeedsReauthorization(claim.authorization)
+        )
+        throw error
+      }
+
+      try {
+        await this.mutations.executeCredentialMutation(
+          claim.authorization,
+          async (executing, signal) => {
+            const refreshed = validateCredentials(
+              await definition.adapter.authentication.refresh(
+                this.adapterContext(definition.id, signal),
+                current
+              )
+            )
+            assertCredentialMutationOperationActive(signal)
+            const normalized = {
+              ...refreshed,
+              ...(refreshed.refreshToken === undefined
+                ? { refreshToken: current.refreshToken }
+                : {}),
+              ...(refreshed.tokenType === undefined && current.tokenType !== undefined
+                ? { tokenType: current.tokenType }
+                : {}),
+              scopes: refreshed.scopes ?? current.scopes ?? authorization.scopes,
+            } satisfies ConnectorOAuthCredentials
+            const envelope = await this.credentials.seal(
+              definition.id,
+              authorization.id,
+              normalized
+            )
+            return this.mutations.stageCredentialMutationCredentials(executing, signal, {
+              credentials: envelope,
+              ...(normalized.expiresAt === undefined
+                ? {}
+                : { credentialExpiresAt: normalized.expiresAt }),
+              scopes: normalized.scopes,
+            })
+          }
+        )
+      } catch (error) {
+        const latest = await recoverConnectorFailure(
+          error,
+          "Connector refresh outcome could not be recovered from storage.",
+          () => this.requireAuthorization(definition.id, authorization.id)
+        )
+        if (this.mutations.isStagedMutation(latest, claim.authorization, "refresh")) {
+          return recoverConnectorFailure(
+            error,
+            "Staged connector refresh could not be finalized during recovery.",
+            () => this.mutations.finalizeStagedMutation(latest)
+          )
+        }
+        if (oauthErrorKind(error) === "retryable") {
+          await recoverConnectorFailure(
+            error,
+            "Connector refresh mutation could not be released after a retryable provider failure.",
+            () => this.mutations.releaseCredentialMutation(claim.authorization)
+          )
+          throw createConnectorCodedError(
+            "connector.provider_unavailable",
+            "Connector credential refresh failed; retry later.",
+            { cause: error }
+          )
+        }
+        const marked = await recoverConnectorFailure(
+          error,
+          "Connector authorization could not be failed closed after an ambiguous refresh.",
+          () => this.mutations.markNeedsReauthorization(claim.authorization)
+        )
+        if (marked) {
+          throw createConnectorCodedError(
+            "connector.authorization_required",
+            "Connector credentials require reauthorization.",
+            { cause: error }
+          )
+        }
+        const recovered = await recoverConnectorFailure(
+          error,
+          "Connector refresh state could not be reloaded after failed closed recovery.",
+          () => this.requireAuthorization(definition.id, authorization.id)
+        )
+        if (recovered.revision !== authorization.revision && recovered.status === "active") {
+          return recovered
+        }
+        throw connectorAuthorizationStatusError(recovered.status)
+      }
+
+      const staged = await this.requireAuthorization(definition.id, authorization.id)
+      return this.mutations.finalizeStagedMutation(staged)
+    })
+  }
+
+  private async requireAuthorization(
+    connectorId: string,
+    authorizationId: string
+  ): Promise<ConnectorAuthorizationRecord> {
+    const authorization = await withConnectorStorageBoundary(
+      "Connector authorization could not be read.",
+      () =>
+        this.storage.getAuthorization({
+          projectId: this.projectId,
+          connectorId,
+          authorizationId,
+        })
+    )
+    if (!authorization) {
+      throw createConnectorCodedError(
+        "connector.not_found",
+        "Connector authorization was not found."
+      )
+    }
+    return authorization
+  }
+
+  private adapterContext(connectorId: string, signal: AbortSignal) {
+    return { projectId: this.projectId, connectorId, signal }
+  }
+}
+
+class RevisionAwareConnectorTokenSource implements ConnectorTokenSource {
+  private rejectedRevision: number | undefined
+
+  constructor(
+    private readonly resolveToken: (rejectedRevision?: number) => Promise<{
+      readonly token: { readonly accessToken: string; readonly tokenType?: string }
+      readonly revision: number
+    }>
+  ) {}
+
+  async get(): Promise<ConnectorAccessToken> {
+    const consumedRejection = this.rejectedRevision
+    const result = await this.resolveToken(consumedRejection)
+    if (this.rejectedRevision === consumedRejection) this.rejectedRevision = undefined
+
+    let invalidated = false
+    return Object.freeze({
+      ...result.token,
+      invalidate: () => {
+        if (invalidated) return
+        invalidated = true
+        this.rejectedRevision = Math.max(this.rejectedRevision ?? -1, result.revision)
+      },
+    })
+  }
+}

package/src/connectors/connections/validation.ts

@@ -0,0 +1,316 @@
+import { createHash } from "node:crypto"
+import type { ConnectorAuthorizationRecord } from "../../storage"
+import { createConnectorCodedError } from "../errors"
+import type { ConnectorAccountCandidate, ConnectorOAuthCredentials } from "../types"
+
+/** Internal validation and normalization shared by the connector connection lifecycle. */
+
+type ConnectorValidationErrorCode =
+  | "connector.adapter_invalid"
+  | "connector.authorization_invalid"
+  | "connector.configuration_invalid"
+
+export function validateCredentials(
+  credentials: ConnectorOAuthCredentials
+): ConnectorOAuthCredentials {
+  if (!isRecord(credentials)) {
+    throw createConnectorCodedError(
+      "connector.adapter_invalid",
+      "OAuth connector adapter returned invalid credentials."
+    )
+  }
+
+  const normalized: {
+    accessToken: string
+    refreshToken?: string
+    tokenType?: string
+    scopes?: string[]
+    expiresAt?: Date
+  } = {
+    accessToken: nonblank(
+      credentials.accessToken,
+      "provider access token",
+      "connector.adapter_invalid"
+    ),
+  }
+
+  if (credentials.refreshToken !== undefined) {
+    normalized.refreshToken = nonblank(
+      credentials.refreshToken,
+      "provider refresh token",
+      "connector.adapter_invalid"
+    )
+  }
+
+  if (credentials.tokenType !== undefined) {
+    normalized.tokenType = nonblank(
+      credentials.tokenType,
+      "provider token type",
+      "connector.adapter_invalid"
+    )
+  }
+
+  if (credentials.scopes !== undefined) {
+    if (!Array.isArray(credentials.scopes)) {
+      throw createConnectorCodedError(
+        "connector.adapter_invalid",
+        "OAuth connector adapter returned invalid scopes."
+      )
+    }
+    normalized.scopes = [
+      ...new Set(
+        credentials.scopes.map((scope) =>
+          nonblank(scope, "provider scope", "connector.adapter_invalid")
+        )
+      ),
+    ]
+  }
+
+  if (credentials.expiresAt !== undefined) {
+    if (!(credentials.expiresAt instanceof Date) || Number.isNaN(credentials.expiresAt.getTime())) {
+      throw createConnectorCodedError(
+        "connector.adapter_invalid",
+        "OAuth connector adapter returned an invalid token expiry."
+      )
+    }
+    normalized.expiresAt = new Date(credentials.expiresAt)
+  }
+
+  return normalized
+}
+
+export function validateAccounts(
+  accounts: readonly ConnectorAccountCandidate[]
+): readonly ConnectorAccountCandidate[] {
+  if (!Array.isArray(accounts)) {
+    throw createConnectorCodedError(
+      "connector.adapter_invalid",
+      "OAuth connector adapter returned an invalid account list."
+    )
+  }
+  const ids = new Set<string>()
+  return accounts.map((account) => {
+    if (!isRecord(account)) {
+      throw createConnectorCodedError(
+        "connector.adapter_invalid",
+        "OAuth connector adapter returned an invalid account."
+      )
+    }
+    const id = nonblank(account.id, "external account id", "connector.adapter_invalid")
+    if (ids.has(id)) {
+      throw createConnectorCodedError(
+        "connector.adapter_invalid",
+        `OAuth connector adapter returned duplicate account '${id}'.`
+      )
+    }
+    ids.add(id)
+    const description =
+      account.description === undefined
+        ? undefined
+        : nonblank(account.description, "external account description", "connector.adapter_invalid")
+    const avatarUrl =
+      account.avatarUrl === undefined
+        ? undefined
+        : normalizedHttpUrl(
+            nonblank(account.avatarUrl, "external account avatar URL", "connector.adapter_invalid"),
+            "external account avatar URL",
+            "connector.adapter_invalid"
+          )
+    return {
+      id,
+      label: nonblank(account.label, "external account label", "connector.adapter_invalid"),
+      ...(description === undefined ? {} : { description }),
+      ...(avatarUrl === undefined ? {} : { avatarUrl }),
+    }
+  })
+}
+
+export function serializeCredentials(credentials: ConnectorOAuthCredentials): string {
+  return JSON.stringify({
+    version: 1,
+    accessToken: credentials.accessToken,
+    ...(credentials.refreshToken === undefined ? {} : { refreshToken: credentials.refreshToken }),
+    ...(credentials.tokenType === undefined ? {} : { tokenType: credentials.tokenType }),
+    ...(credentials.scopes === undefined ? {} : { scopes: credentials.scopes }),
+    ...(credentials.expiresAt === undefined
+      ? {}
+      : { expiresAt: credentials.expiresAt.toISOString() }),
+  })
+}
+
+export function parseCredentials(serialized: string): ConnectorOAuthCredentials {
+  let value: unknown
+  try {
+    value = JSON.parse(serialized)
+  } catch (error) {
+    throw createConnectorCodedError(
+      "connector.credentials_unavailable",
+      "Stored connector credentials are invalid.",
+      { cause: error }
+    )
+  }
+  if (!isRecord(value) || value.version !== 1 || typeof value.accessToken !== "string") {
+    throw createConnectorCodedError(
+      "connector.credentials_unavailable",
+      "Stored connector credentials are invalid."
+    )
+  }
+  if (
+    (value.refreshToken !== undefined && typeof value.refreshToken !== "string") ||
+    (value.tokenType !== undefined && typeof value.tokenType !== "string") ||
+    (value.scopes !== undefined &&
+      (!Array.isArray(value.scopes) || value.scopes.some((scope) => typeof scope !== "string"))) ||
+    (value.expiresAt !== undefined && typeof value.expiresAt !== "string")
+  ) {
+    throw createConnectorCodedError(
+      "connector.credentials_unavailable",
+      "Stored connector credentials are invalid."
+    )
+  }
+  const expiresAt = value.expiresAt === undefined ? undefined : new Date(value.expiresAt)
+  try {
+    return validateCredentials({
+      accessToken: value.accessToken,
+      ...(value.refreshToken === undefined ? {} : { refreshToken: value.refreshToken }),
+      ...(value.tokenType === undefined ? {} : { tokenType: value.tokenType }),
+      ...(value.scopes === undefined ? {} : { scopes: value.scopes as string[] }),
+      ...(expiresAt === undefined ? {} : { expiresAt }),
+    })
+  } catch (error) {
+    throw createConnectorCodedError(
+      "connector.credentials_unavailable",
+      "Stored connector credentials are invalid.",
+      { cause: error }
+    )
+  }
+}
+
+export function shouldRefresh(
+  authorization: ConnectorAuthorizationRecord,
+  now: Date,
+  skewMs: number
+): boolean {
+  return (
+    authorization.credentialExpiresAt !== undefined &&
+    authorization.credentialExpiresAt.getTime() <= now.getTime() + skewMs
+  )
+}
+
+export function tokenView(credentials: ConnectorOAuthCredentials) {
+  return {
+    accessToken: credentials.accessToken,
+    ...(credentials.tokenType === undefined ? {} : { tokenType: credentials.tokenType }),
+  }
+}
+
+export function parseAttemptId(state: string): string {
+  const separator = state.indexOf(".")
+  if (separator <= 0 || separator === state.length - 1) {
+    throw createConnectorCodedError("connector.authorization_invalid", "OAuth state is invalid.")
+  }
+  return state.slice(0, separator)
+}
+
+export function hashSecret(value: string): string {
+  return createHash("sha256").update(value).digest("base64url")
+}
+
+export function normalizedHttpUrl(
+  value: string | URL,
+  field: string,
+  code: ConnectorValidationErrorCode = "connector.configuration_invalid"
+): string {
+  let url: URL
+  try {
+    if (typeof value !== "string" && !(value instanceof URL)) throw new Error("invalid URL")
+    url = new URL(value)
+  } catch (error) {
+    throw createConnectorCodedError(code, `${field} must be an absolute URL.`, { cause: error })
+  }
+  if (url.username || url.password) {
+    throw createConnectorCodedError(code, `${field} must not contain credentials.`)
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) {
+    throw createConnectorCodedError(code, `${field} must use HTTPS, except on a loopback host.`)
+  }
+  return url.toString()
+}
+
+export function assertAuthorizationUrlParameters(
+  authorizationUrl: string,
+  expected: { readonly state: string; readonly codeChallenge: string }
+): void {
+  const parameters = new URL(authorizationUrl).searchParams
+  if (
+    !sameSingleParameter(parameters, "state", expected.state) ||
+    !sameSingleParameter(parameters, "code_challenge", expected.codeChallenge) ||
+    !sameSingleParameter(parameters, "code_challenge_method", "S256")
+  ) {
+    throw createConnectorCodedError(
+      "connector.adapter_invalid",
+      "OAuth connector authorization URL must preserve the framework-provided state and PKCE S256 parameters."
+    )
+  }
+}
+
+export function nonblank(
+  value: unknown,
+  field: string,
+  code: ConnectorValidationErrorCode = "connector.configuration_invalid"
+): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw createConnectorCodedError(code, `${field} must be a non-empty string.`)
+  }
+  return value
+}
+
+export function positiveDuration(value: number, field: string): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      `Connector ${field} must be a positive duration.`
+    )
+  }
+  return value
+}
+
+export function nonNegativeDuration(value: number, field: string): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      `Connector ${field} must not be negative.`
+    )
+  }
+  return value
+}
+
+export function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+export function sameIds(left: readonly string[], right: readonly string[]): boolean {
+  const leftSorted = [...left].sort()
+  const rightSorted = [...right].sort()
+  return (
+    leftSorted.length === rightSorted.length &&
+    leftSorted.every((value, index) => value === rightSorted[index])
+  )
+}
+
+function sameSingleParameter(parameters: URLSearchParams, name: string, expected: string): boolean {
+  const values = parameters.getAll(name)
+  return values.length === 1 && values[0] === expected
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname === "127.0.0.1" ||
+    hostname === "[::1]"
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}

package/src/connectors/connections/views.ts

@@ -0,0 +1,37 @@
+import type { ConnectorAuthorizationRecord, ConnectorConnectionRecord } from "../../storage"
+import { createConnectorCodedError } from "../errors"
+import type { ConnectorConnectionSelector } from "../types"
+import type { ConnectorConnectionView } from "./contracts"
+import { nonblank } from "./validation"
+
+/** V1 accepts only project-owned slots; future owner kinds remain explicit extensions. */
+export function assertConnectorConnectionSelector(selector: ConnectorConnectionSelector): void {
+  if (selector.owner.type !== "project") {
+    throw createConnectorCodedError(
+      "connector.configuration_invalid",
+      "Connector connections only support project ownership in V1."
+    )
+  }
+  nonblank(selector.slot, "connection slot")
+}
+
+export function connectorConnectionView(
+  connection: ConnectorConnectionRecord,
+  status: ConnectorAuthorizationRecord["status"]
+): ConnectorConnectionView {
+  return {
+    id: connection.id,
+    connectorId: connection.connectorId,
+    owner: connection.owner,
+    slot: connection.slot,
+    account: connection.account,
+    status:
+      connection.status === "disconnected" ||
+      status === "revoked" ||
+      status === "revocation_pending"
+        ? "disconnected"
+        : status === "active"
+          ? "connected"
+          : "needs_reauthorization",
+  }
+}