create-safest-tools 0.2.0

package/template/src/connection-oauth.ts

@@ -0,0 +1,368 @@
+import { canonicalJson } from "./audit";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function now(): string { return new Date().toISOString(); }
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+  const binary = atob(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "="));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function randomToken(bytes = 32): string {
+  const value = new Uint8Array(bytes);
+  crypto.getRandomValues(value);
+  return base64Url(value);
+}
+
+async function encryptionKey(secret: string): Promise<CryptoKey> {
+  if (secret.length < 32) throw new ApiError(503, "credential_encryption_unavailable", "Credential encryption is not configured.");
+  return crypto.subtle.importKey("raw", await crypto.subtle.digest("SHA-256", encoder.encode(secret)), { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+
+export async function encryptCredential(secret: string, plaintext: string, context: string): Promise<string> {
+  const iv = new Uint8Array(12);
+  crypto.getRandomValues(iv);
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: encoder.encode(context) },
+    await encryptionKey(secret),
+    encoder.encode(plaintext),
+  ));
+  const packed = new Uint8Array(iv.byteLength + ciphertext.byteLength);
+  packed.set(iv);
+  packed.set(ciphertext, iv.byteLength);
+  return `v1.${base64Url(packed)}`;
+}
+
+export async function decryptCredential(secret: string, value: string, context: string): Promise<string> {
+  if (!value.startsWith("v1.")) throw new ApiError(503, "credential_ciphertext_invalid", "Stored connection credentials are invalid.");
+  try {
+    const packed = fromBase64Url(value.slice(3));
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: packed.slice(0, 12), additionalData: encoder.encode(context) },
+      await encryptionKey(secret),
+      packed.slice(12),
+    );
+    return decoder.decode(plaintext);
+  } catch {
+    throw new ApiError(503, "credential_decryption_failed", "Stored connection credentials could not be decrypted.");
+  }
+}
+
+interface OAuthConfiguration {
+  authorizationUrl: string;
+  tokenUrl: string;
+  revokeUrl: string | null;
+  clientId: string;
+  clientSecretReference: string | null;
+  scopes: string[];
+  authorizationParameters: Record<string, string>;
+}
+
+function publicHttpsUrl(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length > 2_048) throw new ApiError(409, "oauth_configuration_invalid", `${field} is required.`);
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+    if (url.protocol !== "https:" || url.username || url.password || url.hash
+      || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")
+      || host === "0.0.0.0" || host === "127.0.0.1" || host === "::1") throw new Error("unsafe");
+    return url.href;
+  } catch {
+    throw new ApiError(409, "oauth_configuration_invalid", `${field} must be a public HTTPS URL.`);
+  }
+}
+
+function oauthConfiguration(value: string): OAuthConfiguration {
+  let raw: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid");
+    raw = parsed as Record<string, unknown>;
+  } catch {
+    throw new ApiError(409, "oauth_configuration_invalid", "The published OAuth configuration is invalid.");
+  }
+  const clientId = typeof raw.client_id === "string" ? raw.client_id.trim() : "";
+  if (!clientId || clientId.length > 500) throw new ApiError(409, "oauth_configuration_invalid", "oauth_configuration.client_id is required.");
+  const scopes = Array.isArray(raw.scopes) && raw.scopes.length <= 100
+    ? raw.scopes.map((scope) => typeof scope === "string" ? scope.trim() : "").filter(Boolean) : [];
+  const authorizationParameters: Record<string, string> = {};
+  if (raw.authorization_parameters && typeof raw.authorization_parameters === "object" && !Array.isArray(raw.authorization_parameters)) {
+    for (const [key, entry] of Object.entries(raw.authorization_parameters as Record<string, unknown>)) {
+      if (!/^[A-Za-z0-9_.~-]{1,100}$/u.test(key) || typeof entry !== "string" || entry.length > 1_000
+        || ["state", "redirect_uri", "client_id", "code_challenge", "response_type"].includes(key)) {
+        throw new ApiError(409, "oauth_configuration_invalid", "authorization_parameters contains an unsafe value.");
+      }
+      authorizationParameters[key] = entry;
+    }
+  }
+  const secretReference = raw.client_secret_reference === undefined || raw.client_secret_reference === null
+    ? null : typeof raw.client_secret_reference === "string" && /^OAUTH_[A-Z0-9_]{2,96}$/u.test(raw.client_secret_reference)
+      ? raw.client_secret_reference : (() => { throw new ApiError(409, "oauth_configuration_invalid", "client_secret_reference is invalid."); })();
+  return {
+    authorizationUrl: publicHttpsUrl(raw.authorization_url, "authorization_url"),
+    tokenUrl: publicHttpsUrl(raw.token_url, "token_url"),
+    revokeUrl: raw.revoke_url ? publicHttpsUrl(raw.revoke_url, "revoke_url") : null,
+    clientId,
+    clientSecretReference: secretReference,
+    scopes,
+    authorizationParameters,
+  };
+}
+
+function secretBinding(env: Env, reference: string | null): string | null {
+  if (!reference) return null;
+  const value = (env as unknown as Record<string, unknown>)[reference];
+  return typeof value === "string" && value.length >= 8 ? value : null;
+}
+
+async function readJsonResponse(response: Response): Promise<Record<string, unknown>> {
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength > 65_536) throw new ApiError(502, "oauth_provider_response_too_large", "The OAuth provider response exceeded the safe limit.");
+  try {
+    const value = JSON.parse(decoder.decode(bytes)) as unknown;
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid");
+    return value as Record<string, unknown>;
+  } catch {
+    throw new ApiError(502, "oauth_provider_response_invalid", "The OAuth provider returned invalid JSON.");
+  }
+}
+
+function tokenFields(value: Record<string, unknown>): { accessToken: string; refreshToken: string | null; tokenType: string; expiresAt: string | null; scopes: string[] } {
+  const accessToken = typeof value.access_token === "string" ? value.access_token : "";
+  if (!accessToken || accessToken.length > 16_384 || /[\r\n]/u.test(accessToken)) throw new ApiError(502, "oauth_access_token_missing", "The OAuth provider did not return a usable access token.");
+  const refreshToken = typeof value.refresh_token === "string" && value.refresh_token.length <= 16_384 && !/[\r\n]/u.test(value.refresh_token) ? value.refresh_token : null;
+  const tokenType = typeof value.token_type === "string" && /^[A-Za-z][A-Za-z0-9._~-]{0,63}$/u.test(value.token_type) ? value.token_type : "Bearer";
+  const expiresIn = Number(value.expires_in);
+  const expiresAt = Number.isFinite(expiresIn) && expiresIn > 0
+    ? new Date(Date.now() + Math.min(expiresIn, 31_536_000) * 1_000).toISOString() : null;
+  const scopes = typeof value.scope === "string" ? value.scope.split(/\s+/u).filter(Boolean).slice(0, 100) : [];
+  return { accessToken, refreshToken, tokenType, expiresAt, scopes };
+}
+
+interface OAuthVersionRow {
+  connectionId: string;
+  versionId: string;
+  oauthConfigurationJson: string;
+}
+
+async function oauthVersion(db: D1Database, connectionId: string): Promise<OAuthVersionRow> {
+  const row = await db.prepare(`
+    SELECT d.id AS connectionId, v.id AS versionId, v.oauth_configuration_json AS oauthConfigurationJson
+    FROM connection_definitions d JOIN connection_versions v ON v.id = d.active_version_id
+    WHERE d.id = ?1 AND d.status != 'archived' AND v.credential_strategy = 'oauth2_authorization_code'
+      AND v.retired_at IS NULL LIMIT 1
+  `).bind(connectionId).first<OAuthVersionRow>();
+  if (!row) throw new ApiError(409, "oauth_connection_unavailable", "The connection has no active authorization-code OAuth version.");
+  return row;
+}
+
+export async function startConnectionOAuth(
+  env: Env,
+  connectionId: string,
+  session: OperatorSession,
+): Promise<{ authorizationUrl: string; expiresAt: string }> {
+  const version = await oauthVersion(env.DB, connectionId);
+  const configuration = oauthConfiguration(version.oauthConfigurationJson);
+  const state = randomToken(32);
+  const verifier = randomToken(48);
+  const challenge = base64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(verifier))));
+  const redirectUri = `${env.PUBLIC_BASE_URL.replace(/\/$/u, "")}/v1/admin/connections/oauth/callback`;
+  const expiresAt = new Date(Date.now() + 10 * 60_000).toISOString();
+  const timestamp = now();
+  await env.DB.prepare(`
+    INSERT INTO connection_oauth_states (
+      id, connection_id, actor_id, state_hash, pkce_verifier_ciphertext,
+      redirect_uri, requested_scopes_json, expires_at, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+  `).bind(
+    crypto.randomUUID(), connectionId, session.actor.id, await sha256(state),
+    await encryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, verifier, `oauth-state:${connectionId}`),
+    redirectUri, canonicalJson(configuration.scopes), expiresAt, timestamp,
+  ).run();
+  const authorization = new URL(configuration.authorizationUrl);
+  authorization.searchParams.set("response_type", "code");
+  authorization.searchParams.set("client_id", configuration.clientId);
+  authorization.searchParams.set("redirect_uri", redirectUri);
+  authorization.searchParams.set("state", state);
+  authorization.searchParams.set("code_challenge", challenge);
+  authorization.searchParams.set("code_challenge_method", "S256");
+  if (configuration.scopes.length) authorization.searchParams.set("scope", configuration.scopes.join(" "));
+  for (const [key, value] of Object.entries(configuration.authorizationParameters)) authorization.searchParams.set(key, value);
+  return { authorizationUrl: authorization.href, expiresAt };
+}
+
+async function tokenExchange(
+  env: Env,
+  configuration: OAuthConfiguration,
+  values: Record<string, string>,
+): Promise<Record<string, unknown>> {
+  const parameters = new URLSearchParams({ client_id: configuration.clientId, ...values });
+  const clientSecret = secretBinding(env, configuration.clientSecretReference);
+  if (configuration.clientSecretReference && !clientSecret) throw new ApiError(503, "oauth_client_secret_unavailable", "The OAuth client secret binding is unavailable.");
+  if (clientSecret) parameters.set("client_secret", clientSecret);
+  let response: Response;
+  try {
+    response = await fetch(configuration.tokenUrl, {
+      method: "POST",
+      headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+      body: parameters,
+      redirect: "error",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch {
+    throw new ApiError(503, "oauth_provider_unavailable", "The OAuth provider could not be reached.");
+  }
+  const result = await readJsonResponse(response);
+  if (!response.ok) throw new ApiError(502, "oauth_token_exchange_failed", "The OAuth provider rejected the token request.", { provider_status: response.status, provider_error: typeof result.error === "string" ? result.error.slice(0, 200) : null });
+  return result;
+}
+
+export async function completeConnectionOAuth(
+  env: Env,
+  state: string,
+  code: string,
+  session: OperatorSession,
+): Promise<{ connectionId: string; connectionVersionId: string; credentialId: string }> {
+  if (state.length < 32 || state.length > 500 || code.length < 1 || code.length > 4_096) throw new ApiError(400, "oauth_callback_invalid", "The OAuth callback is invalid.");
+  const stored = await env.DB.prepare(`
+    SELECT id, connection_id AS connectionId, actor_id AS actorId,
+      pkce_verifier_ciphertext AS verifierCiphertext, redirect_uri AS redirectUri,
+      requested_scopes_json AS requestedScopesJson, expires_at AS expiresAt, consumed_at AS consumedAt
+    FROM connection_oauth_states WHERE state_hash = ?1 LIMIT 1
+  `).bind(await sha256(state)).first<{
+    id: string; connectionId: string; actorId: string; verifierCiphertext: string;
+    redirectUri: string; requestedScopesJson: string; expiresAt: string; consumedAt: string | null;
+  }>();
+  if (!stored || stored.actorId !== session.actor.id || stored.consumedAt || stored.expiresAt <= now()) {
+    throw new ApiError(400, "oauth_state_invalid", "The OAuth state is invalid, expired, consumed, or belongs to another operator.");
+  }
+  const version = await oauthVersion(env.DB, stored.connectionId);
+  const configuration = oauthConfiguration(version.oauthConfigurationJson);
+  const verifier = await decryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, stored.verifierCiphertext, `oauth-state:${stored.connectionId}`);
+  const timestamp = now();
+  const claimed = await env.DB.prepare(`
+    UPDATE connection_oauth_states SET consumed_at = ?2
+    WHERE id = ?1 AND consumed_at IS NULL AND expires_at > ?2
+  `).bind(stored.id, timestamp).run();
+  if (claimed.meta.changes !== 1) throw new ApiError(400, "oauth_state_consumed", "The OAuth state was already consumed.");
+  const result = tokenFields(await tokenExchange(env, configuration, {
+    grant_type: "authorization_code", code, redirect_uri: stored.redirectUri, code_verifier: verifier,
+  }));
+  const credentialId = crypto.randomUUID();
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT INTO connection_credentials (
+        id, connection_version_id, strategy, encrypted_access_token,
+        encrypted_refresh_token, token_type, granted_scopes_json, expires_at,
+        status, created_at, updated_at
+      ) VALUES (?1, ?2, 'oauth2_authorization_code', ?3, ?4, ?5, ?6, ?7, 'active', ?8, ?8)
+      ON CONFLICT(connection_version_id) DO UPDATE SET
+        encrypted_access_token = excluded.encrypted_access_token,
+        encrypted_refresh_token = excluded.encrypted_refresh_token,
+        token_type = excluded.token_type, granted_scopes_json = excluded.granted_scopes_json,
+        expires_at = excluded.expires_at, status = 'active', last_error_code = NULL,
+        updated_at = excluded.updated_at
+    `).bind(
+      credentialId, version.versionId,
+      await encryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, result.accessToken, `oauth-access:${version.versionId}`),
+      result.refreshToken ? await encryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, result.refreshToken, `oauth-refresh:${version.versionId}`) : null,
+      result.tokenType, canonicalJson(result.scopes.length ? result.scopes : JSON.parse(stored.requestedScopesJson)),
+      result.expiresAt, timestamp,
+    ),
+    env.DB.prepare(`INSERT OR IGNORE INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'connection.oauth_connected', ?3, ?4, 'connection', ?5, ?6, ?7)`)
+      .bind(crypto.randomUUID(), `connection-oauth:${stored.id}`, session.actor.type, session.actor.id, stored.connectionId, canonicalJson({ connectionVersionId: version.versionId, scopes: result.scopes }), timestamp),
+  ]);
+  const current = await env.DB.prepare(`SELECT id FROM connection_credentials WHERE connection_version_id = ?1`).bind(version.versionId).first<{ id: string }>();
+  return { connectionId: stored.connectionId, connectionVersionId: version.versionId, credentialId: current?.id ?? credentialId };
+}
+
+export async function revokeConnectionOAuth(
+  env: Env,
+  connectionId: string,
+  session: OperatorSession,
+): Promise<{ connectionId: string; revoked: boolean }> {
+  const version = await oauthVersion(env.DB, connectionId);
+  const configuration = oauthConfiguration(version.oauthConfigurationJson);
+  const credential = await env.DB.prepare(`SELECT id, encrypted_access_token AS accessToken FROM connection_credentials WHERE connection_version_id = ?1 AND status != 'revoked' LIMIT 1`)
+    .bind(version.versionId).first<{ id: string; accessToken: string | null }>();
+  if (!credential) return { connectionId, revoked: false };
+  if (configuration.revokeUrl && credential.accessToken) {
+    const token = await decryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, credential.accessToken, `oauth-access:${version.versionId}`);
+    const parameters = new URLSearchParams({ token, client_id: configuration.clientId });
+    const clientSecret = secretBinding(env, configuration.clientSecretReference);
+    if (clientSecret) parameters.set("client_secret", clientSecret);
+    let response: Response;
+    try {
+      response = await fetch(configuration.revokeUrl, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: parameters, redirect: "error", signal: AbortSignal.timeout(15_000) });
+    } catch {
+      throw new ApiError(503, "oauth_provider_unavailable", "The OAuth provider could not be reached for revocation.");
+    }
+    if (!response.ok) throw new ApiError(502, "oauth_revocation_failed", "The OAuth provider rejected revocation.", { provider_status: response.status });
+  }
+  const timestamp = now();
+  await env.DB.batch([
+    env.DB.prepare(`UPDATE connection_credentials SET status = 'revoked', encrypted_access_token = NULL, encrypted_refresh_token = NULL, updated_at = ?2 WHERE id = ?1`).bind(credential.id, timestamp),
+    env.DB.prepare(`INSERT OR IGNORE INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'connection.oauth_revoked', ?3, ?4, 'connection', ?5, ?6, ?7)`)
+      .bind(crypto.randomUUID(), `connection-oauth-revoke:${credential.id}`, session.actor.type, session.actor.id, connectionId, canonicalJson({ connectionVersionId: version.versionId }), timestamp),
+  ]);
+  return { connectionId, revoked: true };
+}
+
+export async function resolveOAuthAccessToken(env: Env, connectionVersionId: string): Promise<{ token: string; tokenType: string }> {
+  const credential = await env.DB.prepare(`
+    SELECT c.id, c.encrypted_access_token AS accessToken, c.encrypted_refresh_token AS refreshToken,
+      c.token_type AS tokenType, c.expires_at AS expiresAt, c.status, c.updated_at AS updatedAt,
+      v.oauth_configuration_json AS oauthConfigurationJson
+    FROM connection_credentials c JOIN connection_versions v ON v.id = c.connection_version_id
+    WHERE c.connection_version_id = ?1 LIMIT 1
+  `).bind(connectionVersionId).first<{
+    id: string; accessToken: string | null; refreshToken: string | null; tokenType: string | null;
+    expiresAt: string | null; status: string; updatedAt: string; oauthConfigurationJson: string;
+  }>();
+  if (!credential || credential.status !== "active" || !credential.accessToken) throw new ApiError(503, "connection_oauth_credential_unavailable", "The OAuth connection is not authorized.");
+  if (!credential.expiresAt || Date.parse(credential.expiresAt) > Date.now() + 60_000) {
+    return { token: await decryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, credential.accessToken, `oauth-access:${connectionVersionId}`), tokenType: credential.tokenType ?? "Bearer" };
+  }
+  if (!credential.refreshToken) throw new ApiError(503, "connection_oauth_refresh_required", "The OAuth access token expired without a refresh token.");
+  const configuration = oauthConfiguration(credential.oauthConfigurationJson);
+  const refreshToken = await decryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, credential.refreshToken, `oauth-refresh:${connectionVersionId}`);
+  try {
+    const refreshed = tokenFields(await tokenExchange(env, configuration, { grant_type: "refresh_token", refresh_token: refreshToken }));
+    const timestamp = now();
+    const updated = await env.DB.prepare(`UPDATE connection_credentials SET encrypted_access_token = ?2, encrypted_refresh_token = COALESCE(?3, encrypted_refresh_token), token_type = ?4, granted_scopes_json = CASE WHEN ?5 = '[]' THEN granted_scopes_json ELSE ?5 END, expires_at = ?6, status = 'active', last_refresh_at = ?7, last_error_code = NULL, updated_at = ?7 WHERE id = ?1 AND updated_at = ?8`)
+      .bind(
+        credential.id,
+        await encryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, refreshed.accessToken, `oauth-access:${connectionVersionId}`),
+        refreshed.refreshToken ? await encryptCredential(env.CREDENTIAL_ENCRYPTION_KEY, refreshed.refreshToken, `oauth-refresh:${connectionVersionId}`) : null,
+        refreshed.tokenType, canonicalJson(refreshed.scopes), refreshed.expiresAt, timestamp, credential.updatedAt,
+      ).run();
+    if (updated.meta.changes !== 1) return resolveOAuthAccessToken(env, connectionVersionId);
+    return { token: refreshed.accessToken, tokenType: refreshed.tokenType };
+  } catch (error) {
+    const current = await env.DB.prepare(`SELECT status, updated_at AS updatedAt FROM connection_credentials WHERE id = ?1 LIMIT 1`)
+      .bind(credential.id).first<{ status: string; updatedAt: string }>();
+    if (current?.status === "active" && current.updatedAt !== credential.updatedAt) return resolveOAuthAccessToken(env, connectionVersionId);
+    await env.DB.prepare(`UPDATE connection_credentials SET status = 'refresh_failed', last_error_code = 'oauth_refresh_failed', updated_at = ?2 WHERE id = ?1 AND updated_at = ?3`)
+      .bind(credential.id, now(), credential.updatedAt).run();
+    throw error;
+  }
+}
+
+export async function pruneConnectionOAuthStates(db: D1Database): Promise<number> {
+  const cutoff = new Date(Date.now() - 24 * 60 * 60_000).toISOString();
+  const result = await db.prepare(`DELETE FROM connection_oauth_states WHERE expires_at <= ?1 OR (consumed_at IS NOT NULL AND consumed_at <= ?1)`)
+    .bind(cutoff).run();
+  return Number(result.meta.changes ?? 0);
+}