@drawbridge/drawbridge-utils 0.0.41 → 0.0.43

package/dist/oauth/index.d.cts

@@ -0,0 +1,231 @@
+import { generate, hash } from '../token.cjs';
+export { compare } from '../token.cjs';
+import 'crypto';
+
+// Shared OAuth helpers used across drawbridge-api, drawbridge-sync,
+// drawbridge-app-web, and any first-party app that needs to participate
+// in the OAuth 2.1 provider:
+//
+//   - scopes, developer: the locked scope vocabulary
+//   - parse, validate, intersect, isDeveloperAllowed: scope set operations
+//   - hashToken, generateToken, compare: opaque-token primitives
+//   - createOAuthClient: cached client_credentials access token getter
+
+
+// ─────────────────────────────────────────────────────────────────────────
+// Scope vocabulary (locked — 15 scopes, 10 in the developer-allowed subset)
+// ─────────────────────────────────────────────────────────────────────────
+
+const scopes = [
+	'profile:read',
+	'profile:write',
+	'organization:read',
+	'organization:write',
+	'campaigns:read',
+	'campaigns:write',
+	'contacts:read',
+	'contacts:write',
+	'workflows:read',
+	'workflows:write',
+	'connections:read',
+	'connections:write',
+	'billing:read',
+	'billing:write',
+	'admin'
+];
+
+// Subset granted to third-party developer apps via /oauth/clients self-service
+// registration. Excludes profile:write (account-level), organization:write
+// (org admin only), billing:* (financial), admin (privileged).
+const developer = [
+	'profile:read',
+	'organization:read',
+	'campaigns:read',
+	'campaigns:write',
+	'contacts:read',
+	'contacts:write',
+	'workflows:read',
+	'workflows:write',
+	'connections:read',
+	'connections:write'
+];
+
+const parse = ( raw ) => {
+
+	if( ! raw ) return [];
+
+	if( Array.isArray( raw ) ) return raw;
+
+	return String( raw ).split( /\s+/ ).filter( Boolean );
+
+};
+
+const validate = ( scopes ) => {
+
+	const parsed = parse( scopes );
+	const invalid = parsed.filter( ( scope ) => ! scopes.includes( scope ) );
+
+	return {
+		invalid,
+		valid : invalid.length === 0
+	};
+
+};
+
+const intersect = ( requested, allowed ) => {
+
+	const r = parse( requested );
+	const a = parse( allowed );
+
+	return r.filter( ( scope ) => a.includes( scope ) );
+
+};
+
+const isDeveloperAllowed = ( scope ) => developer.includes( scope );
+
+// ─────────────────────────────────────────────────────────────────────────
+// Token primitives — convenience wrappers over drawbridge-utils/token that
+// fix the OAuth-specific conventions (32 bytes base64url, env-keyed HMAC)
+// ─────────────────────────────────────────────────────────────────────────
+
+// Hash an OAuth token with the deployment's HMAC key (OAUTH_TOKEN_HMAC_KEY).
+// Falls back to plain SHA256 if the env var is unset — fine for local dev,
+// not for production (DB compromise would then allow token forgery).
+const hashToken = ( raw ) => hash( raw, process.env.OAUTH_TOKEN_HMAC_KEY );
+
+// 32 cryptographically random bytes encoded as a 43-char base64url string —
+// the shape used for access tokens, refresh tokens, PATs, and authorization
+// codes.
+const generateToken = () => generate( 32, 'base64url' );
+
+// ─────────────────────────────────────────────────────────────────────────
+// Client_credentials token caching for first-party apps that call
+// drawbridge-api as themselves (drawbridge-share, drawbridge-emails,
+// drawbridge-webhooks, etc.).
+//
+// Caches the access token in process memory; refreshes when nearing expiry
+// or after a 401. Single-flight refresh prevents thundering herd when many
+// concurrent requests arrive while the token is being rotated.
+//
+// Usage:
+//   import { createOAuthClient } from '@drawbridge/drawbridge-utils/oauth';
+//
+//   const client = createOAuthClient({
+//       clientId : process.env.OAUTH_CLIENT_ID,
+//       clientSecret : process.env.OAUTH_CLIENT_SECRET,
+//       tokenUri : process.env.NEXT_PUBLIC_API_URI + '/oauth/token',
+//       scopes : [ 'campaigns:read' ]
+//   });
+//
+//   await request({ endpoint : '/page/abc', token : await client.token() });
+// ─────────────────────────────────────────────────────────────────────────
+
+const REFRESH_LEAD_SECONDS = 60;
+
+const createOAuthClient = ({
+	clientId,
+	clientSecret,
+	scopes = [],
+	tokenUri
+}) => {
+
+	if( ! clientId ) throw new Error( 'createOAuthClient: clientId required' );
+	if( ! clientSecret ) throw new Error( 'createOAuthClient: clientSecret required' );
+	if( ! tokenUri ) throw new Error( 'createOAuthClient: tokenUri required' );
+
+	let cached = null;
+	let pending = null;
+
+	const isFresh = () => {
+
+		if( ! cached ) return false;
+
+		const now = Math.floor( Date.now() / 1000 );
+
+		return cached.expiresAt - REFRESH_LEAD_SECONDS > now;
+
+	};
+
+	const fetchToken = async () => {
+
+		const params = new URLSearchParams();
+
+		params.set( 'grant_type', 'client_credentials' );
+
+		if( scopes.length > 0 ){
+
+			params.set( 'scope', scopes.join( ' ' ) );
+
+		}
+
+		const basic = Buffer
+			.from( clientId + ':' + clientSecret )
+			.toString( 'base64' );
+
+		const response = await fetch(
+			tokenUri,
+			{
+				body : params.toString(),
+				headers : {
+					'authorization' : 'Basic ' + basic,
+					'content-type' : 'application/x-www-form-urlencoded'
+				},
+				method : 'POST'
+			}
+		);
+
+		if( ! response.ok ){
+
+			const text = await response.text();
+
+			throw new Error( 'createOAuthClient: token fetch failed (' + response.status + '): ' + text );
+
+		}
+
+		const body = await response.json();
+
+		cached = {
+			accessToken : body.access_token,
+			expiresAt : Math.floor( Date.now() / 1000 ) + Number( body.expires_in || 3600 ),
+			scope : body.scope
+		};
+
+		return cached.accessToken;
+
+	};
+
+	// Single-flight: collapse concurrent token fetches into one network call.
+	const refresh = () => {
+
+		if( pending ) return pending;
+
+		pending = fetchToken().finally( () => {
+
+			pending = null;
+
+		});
+
+		return pending;
+
+	};
+
+	return {
+		token : async () => {
+
+			if( isFresh() ) return cached.accessToken;
+
+			return refresh();
+
+		},
+		// Force a refresh on the next call. Use this when a request returns 401
+		// before the cached token's expiry — the server may have revoked it.
+		invalidate : () => {
+
+			cached = null;
+
+		}
+	};
+
+};
+
+export { createOAuthClient, developer, generateToken, hashToken, intersect, isDeveloperAllowed, parse, scopes, validate };

package/dist/oauth/index.d.ts

@@ -0,0 +1,231 @@
+import { generate, hash } from '../token.js';
+export { compare } from '../token.js';
+import 'crypto';
+
+// Shared OAuth helpers used across drawbridge-api, drawbridge-sync,
+// drawbridge-app-web, and any first-party app that needs to participate
+// in the OAuth 2.1 provider:
+//
+//   - scopes, developer: the locked scope vocabulary
+//   - parse, validate, intersect, isDeveloperAllowed: scope set operations
+//   - hashToken, generateToken, compare: opaque-token primitives
+//   - createOAuthClient: cached client_credentials access token getter
+
+
+// ─────────────────────────────────────────────────────────────────────────
+// Scope vocabulary (locked — 15 scopes, 10 in the developer-allowed subset)
+// ─────────────────────────────────────────────────────────────────────────
+
+const scopes = [
+	'profile:read',
+	'profile:write',
+	'organization:read',
+	'organization:write',
+	'campaigns:read',
+	'campaigns:write',
+	'contacts:read',
+	'contacts:write',
+	'workflows:read',
+	'workflows:write',
+	'connections:read',
+	'connections:write',
+	'billing:read',
+	'billing:write',
+	'admin'
+];
+
+// Subset granted to third-party developer apps via /oauth/clients self-service
+// registration. Excludes profile:write (account-level), organization:write
+// (org admin only), billing:* (financial), admin (privileged).
+const developer = [
+	'profile:read',
+	'organization:read',
+	'campaigns:read',
+	'campaigns:write',
+	'contacts:read',
+	'contacts:write',
+	'workflows:read',
+	'workflows:write',
+	'connections:read',
+	'connections:write'
+];
+
+const parse = ( raw ) => {
+
+	if( ! raw ) return [];
+
+	if( Array.isArray( raw ) ) return raw;
+
+	return String( raw ).split( /\s+/ ).filter( Boolean );
+
+};
+
+const validate = ( scopes ) => {
+
+	const parsed = parse( scopes );
+	const invalid = parsed.filter( ( scope ) => ! scopes.includes( scope ) );
+
+	return {
+		invalid,
+		valid : invalid.length === 0
+	};
+
+};
+
+const intersect = ( requested, allowed ) => {
+
+	const r = parse( requested );
+	const a = parse( allowed );
+
+	return r.filter( ( scope ) => a.includes( scope ) );
+
+};
+
+const isDeveloperAllowed = ( scope ) => developer.includes( scope );
+
+// ─────────────────────────────────────────────────────────────────────────
+// Token primitives — convenience wrappers over drawbridge-utils/token that
+// fix the OAuth-specific conventions (32 bytes base64url, env-keyed HMAC)
+// ─────────────────────────────────────────────────────────────────────────
+
+// Hash an OAuth token with the deployment's HMAC key (OAUTH_TOKEN_HMAC_KEY).
+// Falls back to plain SHA256 if the env var is unset — fine for local dev,
+// not for production (DB compromise would then allow token forgery).
+const hashToken = ( raw ) => hash( raw, process.env.OAUTH_TOKEN_HMAC_KEY );
+
+// 32 cryptographically random bytes encoded as a 43-char base64url string —
+// the shape used for access tokens, refresh tokens, PATs, and authorization
+// codes.
+const generateToken = () => generate( 32, 'base64url' );
+
+// ─────────────────────────────────────────────────────────────────────────
+// Client_credentials token caching for first-party apps that call
+// drawbridge-api as themselves (drawbridge-share, drawbridge-emails,
+// drawbridge-webhooks, etc.).
+//
+// Caches the access token in process memory; refreshes when nearing expiry
+// or after a 401. Single-flight refresh prevents thundering herd when many
+// concurrent requests arrive while the token is being rotated.
+//
+// Usage:
+//   import { createOAuthClient } from '@drawbridge/drawbridge-utils/oauth';
+//
+//   const client = createOAuthClient({
+//       clientId : process.env.OAUTH_CLIENT_ID,
+//       clientSecret : process.env.OAUTH_CLIENT_SECRET,
+//       tokenUri : process.env.NEXT_PUBLIC_API_URI + '/oauth/token',
+//       scopes : [ 'campaigns:read' ]
+//   });
+//
+//   await request({ endpoint : '/page/abc', token : await client.token() });
+// ─────────────────────────────────────────────────────────────────────────
+
+const REFRESH_LEAD_SECONDS = 60;
+
+const createOAuthClient = ({
+	clientId,
+	clientSecret,
+	scopes = [],
+	tokenUri
+}) => {
+
+	if( ! clientId ) throw new Error( 'createOAuthClient: clientId required' );
+	if( ! clientSecret ) throw new Error( 'createOAuthClient: clientSecret required' );
+	if( ! tokenUri ) throw new Error( 'createOAuthClient: tokenUri required' );
+
+	let cached = null;
+	let pending = null;
+
+	const isFresh = () => {
+
+		if( ! cached ) return false;
+
+		const now = Math.floor( Date.now() / 1000 );
+
+		return cached.expiresAt - REFRESH_LEAD_SECONDS > now;
+
+	};
+
+	const fetchToken = async () => {
+
+		const params = new URLSearchParams();
+
+		params.set( 'grant_type', 'client_credentials' );
+
+		if( scopes.length > 0 ){
+
+			params.set( 'scope', scopes.join( ' ' ) );
+
+		}
+
+		const basic = Buffer
+			.from( clientId + ':' + clientSecret )
+			.toString( 'base64' );
+
+		const response = await fetch(
+			tokenUri,
+			{
+				body : params.toString(),
+				headers : {
+					'authorization' : 'Basic ' + basic,
+					'content-type' : 'application/x-www-form-urlencoded'
+				},
+				method : 'POST'
+			}
+		);
+
+		if( ! response.ok ){
+
+			const text = await response.text();
+
+			throw new Error( 'createOAuthClient: token fetch failed (' + response.status + '): ' + text );
+
+		}
+
+		const body = await response.json();
+
+		cached = {
+			accessToken : body.access_token,
+			expiresAt : Math.floor( Date.now() / 1000 ) + Number( body.expires_in || 3600 ),
+			scope : body.scope
+		};
+
+		return cached.accessToken;
+
+	};
+
+	// Single-flight: collapse concurrent token fetches into one network call.
+	const refresh = () => {
+
+		if( pending ) return pending;
+
+		pending = fetchToken().finally( () => {
+
+			pending = null;
+
+		});
+
+		return pending;
+
+	};
+
+	return {
+		token : async () => {
+
+			if( isFresh() ) return cached.accessToken;
+
+			return refresh();
+
+		},
+		// Force a refresh on the next call. Use this when a request returns 401
+		// before the cached token's expiry — the server may have revoked it.
+		invalidate : () => {
+
+			cached = null;
+
+		}
+	};
+
+};
+
+export { createOAuthClient, developer, generateToken, hashToken, intersect, isDeveloperAllowed, parse, scopes, validate };

package/dist/oauth/index.js

@@ -0,0 +1,151 @@
+// lib/token.js
+import crypto from "crypto";
+var generate = (bytes = 32, encoding = "base64url") => {
+  const buf = crypto.randomBytes(bytes);
+  return encoding ? buf.toString(encoding) : buf;
+};
+var hash = (value, key) => {
+  if (!value) return null;
+  if (key) {
+    return crypto.createHmac("sha256", key).update(String(value)).digest("base64url");
+  }
+  return crypto.createHash("sha256").update(String(value)).digest("base64url");
+};
+var compare = (a, b) => {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(
+    Buffer.from(a),
+    Buffer.from(b)
+  );
+};
+
+// lib/oauth/index.js
+var scopes = [
+  "profile:read",
+  "profile:write",
+  "organization:read",
+  "organization:write",
+  "campaigns:read",
+  "campaigns:write",
+  "contacts:read",
+  "contacts:write",
+  "workflows:read",
+  "workflows:write",
+  "connections:read",
+  "connections:write",
+  "billing:read",
+  "billing:write",
+  "admin"
+];
+var developer = [
+  "profile:read",
+  "organization:read",
+  "campaigns:read",
+  "campaigns:write",
+  "contacts:read",
+  "contacts:write",
+  "workflows:read",
+  "workflows:write",
+  "connections:read",
+  "connections:write"
+];
+var parse = (raw) => {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  return String(raw).split(/\s+/).filter(Boolean);
+};
+var validate = (scopes2) => {
+  const parsed = parse(scopes2);
+  const invalid = parsed.filter((scope) => !scopes2.includes(scope));
+  return {
+    invalid,
+    valid: invalid.length === 0
+  };
+};
+var intersect = (requested, allowed) => {
+  const r = parse(requested);
+  const a = parse(allowed);
+  return r.filter((scope) => a.includes(scope));
+};
+var isDeveloperAllowed = (scope) => developer.includes(scope);
+var hashToken = (raw) => hash(raw, process.env.OAUTH_TOKEN_HMAC_KEY);
+var generateToken = () => generate(32, "base64url");
+var REFRESH_LEAD_SECONDS = 60;
+var createOAuthClient = ({
+  clientId,
+  clientSecret,
+  scopes: scopes2 = [],
+  tokenUri
+}) => {
+  if (!clientId) throw new Error("createOAuthClient: clientId required");
+  if (!clientSecret) throw new Error("createOAuthClient: clientSecret required");
+  if (!tokenUri) throw new Error("createOAuthClient: tokenUri required");
+  let cached = null;
+  let pending = null;
+  const isFresh = () => {
+    if (!cached) return false;
+    const now = Math.floor(Date.now() / 1e3);
+    return cached.expiresAt - REFRESH_LEAD_SECONDS > now;
+  };
+  const fetchToken = async () => {
+    const params = new URLSearchParams();
+    params.set("grant_type", "client_credentials");
+    if (scopes2.length > 0) {
+      params.set("scope", scopes2.join(" "));
+    }
+    const basic = Buffer.from(clientId + ":" + clientSecret).toString("base64");
+    const response = await fetch(
+      tokenUri,
+      {
+        body: params.toString(),
+        headers: {
+          "authorization": "Basic " + basic,
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        method: "POST"
+      }
+    );
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error("createOAuthClient: token fetch failed (" + response.status + "): " + text);
+    }
+    const body = await response.json();
+    cached = {
+      accessToken: body.access_token,
+      expiresAt: Math.floor(Date.now() / 1e3) + Number(body.expires_in || 3600),
+      scope: body.scope
+    };
+    return cached.accessToken;
+  };
+  const refresh = () => {
+    if (pending) return pending;
+    pending = fetchToken().finally(() => {
+      pending = null;
+    });
+    return pending;
+  };
+  return {
+    token: async () => {
+      if (isFresh()) return cached.accessToken;
+      return refresh();
+    },
+    // Force a refresh on the next call. Use this when a request returns 401
+    // before the cached token's expiry — the server may have revoked it.
+    invalidate: () => {
+      cached = null;
+    }
+  };
+};
+export {
+  compare,
+  createOAuthClient,
+  developer,
+  generateToken,
+  hashToken,
+  intersect,
+  isDeveloperAllowed,
+  parse,
+  scopes,
+  validate
+};