@omega.js/backend 0.1.0

package/dist/manager/routes/user/connections/_state.js

@@ -0,0 +1,117 @@
+/**
+ * The one-time secrets a connect is made of
+ * ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)): the CSRF token,
+ * the PKCE pair, and the encrypted state that carries a leg across the trip to
+ * the provider and back.
+ *
+ * One concern, one file: nothing here loads a provider or talks to one.
+ */
+
+const crypto = require('crypto');
+const env = require('../../../libraries/env.js');
+
+// How long an encrypted state is good for
+const STATE_TTL_MINUTES = 10;
+
+// Derive the connection state encryption key from OMEGA_ADMIN_KEY
+const STATE_KEY = env.get('OMEGA_ADMIN_KEY')
+  ? crypto.createHash('sha256').update(`connections-state:${env.get('OMEGA_ADMIN_KEY')}`).digest('hex')
+  : null;
+
+/**
+ * A fresh CSRF token for one authorize leg.
+ *
+ * @returns {string} 32 random bytes, hex
+ */
+function generateCsrfToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * The PKCE challenge for a verifier — S256, the only method the lane mints
+ * (RFC 7636 §4.2: base64url(sha256(verifier)), no padding).
+ *
+ * @param {string} verifier - The code verifier
+ * @returns {string} The code challenge
+ */
+function pkceChallenge(verifier) {
+  return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Mint one PKCE pair for an authorize leg
+ * ([#771](https://github.com/Omega-JS-Stack/omega/issues/771)). The CHALLENGE
+ * rides the authorize URL; the VERIFIER stays server-side beside the CSRF
+ * token in `usage/<uid>` until the exchange proves it.
+ *
+ * @returns {{ verifier: string, challenge: string }} The pair
+ */
+function generatePkcePair() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+
+  return { verifier, challenge: pkceChallenge(verifier) };
+}
+
+/**
+ * Encrypt one authorize leg's state (AES-256-GCM, our key).
+ *
+ * @param {object} data - The state to carry
+ * @returns {string} `<iv>.<ciphertext>.<authTag>`, base64 each
+ */
+function encryptState(data) {
+  if (!STATE_KEY) {
+    throw new Error('OMEGA_ADMIN_KEY not configured');
+  }
+
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv('aes-256-gcm', Buffer.from(STATE_KEY, 'hex'), iv);
+
+  let encrypted = cipher.update(JSON.stringify(data), 'utf8', 'base64');
+  encrypted += cipher.final('base64');
+
+  const authTag = cipher.getAuthTag().toString('base64');
+
+  return `${iv.toString('base64')}.${encrypted}.${authTag}`;
+}
+
+/**
+ * Read a state back, or throw — a tampered one never decrypts.
+ *
+ * @param {string} encryptedState - What the provider handed back
+ * @returns {object} The state as it was written
+ */
+function decryptState(encryptedState) {
+  if (!STATE_KEY) {
+    throw new Error('OMEGA_ADMIN_KEY not configured');
+  }
+
+  const parts = encryptedState.split('.');
+
+  if (parts.length !== 3) {
+    throw new Error('Invalid state format');
+  }
+
+  const [ivB64, encryptedB64, authTagB64] = parts;
+
+  const iv = Buffer.from(ivB64, 'base64');
+  const encrypted = Buffer.from(encryptedB64, 'base64');
+  const authTag = Buffer.from(authTagB64, 'base64');
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(STATE_KEY, 'hex'), iv);
+  decipher.setAuthTag(authTag);
+
+  let decrypted = decipher.update(encrypted, 'base64', 'utf8');
+  decrypted += decipher.final('utf8');
+
+  return JSON.parse(decrypted);
+}
+
+module.exports = {
+  STATE_TTL_MINUTES,
+  STATE_KEY,
+  generateCsrfToken,
+  generatePkcePair,
+  pkceChallenge,
+  encryptState,
+  decryptState,
+};

package/dist/manager/routes/user/connections/delete.js

@@ -0,0 +1,55 @@
+const { FieldValue } = require('firebase-admin/firestore');
+const { buildContext } = require('./_context.js');
+const { buildGrantContext, runStep, REVOKE_UNSUPPORTED } = require('./_grant.js');
+
+/**
+ * DELETE /user/connections - Remove a connection
+ *
+ * Revokes tokens with the provider (best effort) and removes the connection.
+ */
+module.exports = async ({ ctx, user, settings }) => {
+  // An admin may pass `uid`: revoking happens AT THE PROVIDER, on the user's
+  // behalf, and needs no browser ([#782](https://github.com/Omega-JS-Stack/omega/issues/782))
+  const context = await buildContext({ ctx, user, settings, honorUid: true });
+
+  if (context.error) {
+    return ctx.respond(context.error.message, { code: context.error.code });
+  }
+
+  const { Manager, admin, connectionProvider, targetUid, targetUser, clientId, clientSecret } = context;
+
+  ctx.log('Connections DELETE request', { provider: settings.provider });
+
+  const storedToken = targetUser?.connections?.[settings.provider]?.token;
+
+  // Revoking is BEST EFFORT and never gates the delete
+  // ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)): the default
+  // step is the RFC 7009 POST, a provider that declares no `urls.revoke` answers
+  // `unsupported` (Spotify has no endpoint at all), and a provider that refuses
+  // throws — the user asked to be disconnected either way.
+  if (storedToken?.access_token) {
+    const outcome = await Promise.resolve()
+      .then(() => runStep(connectionProvider, 'revoke', buildGrantContext({
+        provider: connectionProvider,
+        providerName: settings.provider,
+        Manager,
+        ctx,
+        uid: targetUid,
+        clientId,
+        clientSecret,
+        token: storedToken,
+      })))
+      .then((answer) => (answer === REVOKE_UNSUPPORTED ? REVOKE_UNSUPPORTED : 'revoked'))
+      .catch((e) => `failed: ${e.message}`);
+
+    ctx.log('Connections revoke', { provider: settings.provider, outcome });
+  }
+
+  // Delete the connection record from the user document
+  await admin.firestore().doc(`users/${targetUid}`).update({
+    [`connections.${settings.provider}`]: FieldValue.delete(),
+    metadata: Manager.Metadata().set({ tag: 'user/connections' }),
+  });
+
+  return ctx.respond({ success: true });
+};

package/dist/manager/routes/user/connections/get.js

@@ -0,0 +1,167 @@
+const { FieldValue } = require('firebase-admin/firestore');
+const { buildContext, returnUrlError } = require('./_context.js');
+const { generateCsrfToken, generatePkcePair, encryptState } = require('./_state.js');
+const { buildGrantContext, runStep } = require('./_grant.js');
+
+/**
+ * GET /user/connections - Read operations
+ *
+ * Actions:
+ *   - authorize (default): Get authorization URL
+ *   - status: Check connection status
+ */
+module.exports = async ({ ctx, user, settings }) => {
+  // `status` takes an admin's `uid` — it checks the connection AT THE PROVIDER
+  // (and may delete a dead one), which a trusted server may do on a user's
+  // behalf. `authorize` does not: the URL it answers is opened by the
+  // connecting user's OWN browser ([#782](https://github.com/Omega-JS-Stack/omega/issues/782))
+  const context = await buildContext({ ctx, user, settings, honorUid: settings.action === 'status' });
+
+  if (context.error) {
+    return ctx.respond(context.error.message, { code: context.error.code });
+  }
+
+  ctx.log('Connections GET request', { action: settings.action, provider: settings.provider });
+
+  switch (settings.action) {
+    case 'status':
+      return processStatus(context);
+
+    case 'authorize':
+    default:
+      return processAuthorize(context);
+  }
+};
+
+// ============================================================================
+// Handlers
+// ============================================================================
+
+async function processAuthorize(context) {
+  const { ctx, Manager, admin, connectionProvider, settings, targetUid, clientId, clientSecret, redirectUri } = context;
+
+  // The optional destination this connect comes back to
+  // ([#784](https://github.com/Omega-JS-Stack/omega/issues/784)): a caller's
+  // value, refused here — before anything is minted — when it is not a path
+  const invalidReturn = returnUrlError(settings);
+
+  if (invalidReturn) {
+    return ctx.respond(invalidReturn.message, { code: invalidReturn.code });
+  }
+
+  if (!clientId) {
+    return ctx.respond(`Missing client_id for ${settings.provider} provider`, { code: 500 });
+  }
+
+  // Generate CSRF token
+  const csrfToken = generateCsrfToken();
+
+  // PKCE, when the provider declares it: the verifier is minted here and rides
+  // the SAME usage entry as the CSRF token, read back (and deleted) at tokenize
+  const pkce = connectionProvider.pkce ? generatePkcePair() : null;
+
+  // Store CSRF token in user's usage document (auto-cleaned daily)
+  await admin.firestore().doc(`usage/${targetUid}`).set({
+    connections: {
+      [settings.provider]: {
+        csrf: csrfToken,
+        // A verifier is a one-time secret, never a log line and never the state
+        verifier: pkce ? pkce.verifier : null,
+        createdAt: Date.now(),
+      },
+    },
+  }, { merge: true });
+
+  // Build minimal state (no unnecessary data)
+  const stateData = {
+    provider: settings.provider,
+    uid: targetUid,
+    csrf: csrfToken,
+    ts: Date.now(),
+    // Where the callback page lands when this connect comes back
+    // ([#784](https://github.com/Omega-JS-Stack/omega/issues/784)). It rides the
+    // ENCRYPTED state because that is the only thing that survives the trip out
+    // to the provider and back, and the key stays absent when no returnUrl was
+    // passed — the page's own default is what answers then
+    ...(settings.returnUrl ? { returnUrl: settings.returnUrl } : {}),
+  };
+
+  // Encrypt state
+  let encryptedState;
+
+  try {
+    encryptedState = encryptState(stateData);
+  } catch (e) {
+    return ctx.respond(e.message, { code: 500 });
+  }
+
+  // Set scopes from app config, fall back to provider defaults
+  const appScopes = Manager.config?.connections?.[settings.provider]?.scope || [];
+  const finalScopes = appScopes.length > 0 ? appScopes : (connectionProvider.scope || []);
+
+  // Build authorization URL — the provider's own step when it declares one
+  const urlString = await runStep(connectionProvider, 'authorize', buildGrantContext({
+    provider: connectionProvider,
+    providerName: settings.provider,
+    Manager,
+    ctx,
+    uid: targetUid,
+    clientId,
+    clientSecret,
+    redirectUri,
+    scope: finalScopes,
+    state: encryptedState,
+    pkce,
+  }));
+
+  ctx.log('Connections authorize URL generated');
+
+  if (settings.redirect) {
+    return ctx.redirect(urlString);
+  }
+
+  return ctx.respond({ url: urlString });
+}
+
+async function processStatus(context) {
+  const { ctx, Manager, admin, connectionProvider, settings, targetUid, targetUser, clientId, clientSecret } = context;
+
+  // `returnUrl` belongs to `authorize` alone; a caller passing it here fails
+  // loudly rather than being silently landed nowhere (the #782 rule for `uid`)
+  if (settings.returnUrl) {
+    return ctx.respond('The returnUrl parameter is only accepted by action=authorize.', { code: 400 });
+  }
+
+  const storedToken = targetUser?.connections?.[settings.provider]?.token;
+
+  if (!storedToken?.refresh_token) {
+    return ctx.respond({ status: 'disconnected' });
+  }
+
+  // A provider that can ASK answers from there; without a `status` step, a
+  // stored refresh token IS the answer — there is nothing else to read
+  if (typeof connectionProvider.status !== 'function') {
+    return ctx.respond({ status: 'connected' });
+  }
+
+  const status = await Promise.resolve().then(() => runStep(connectionProvider, 'status', buildGrantContext({
+    provider: connectionProvider,
+    providerName: settings.provider,
+    Manager,
+    ctx,
+    uid: targetUid,
+    clientId,
+    clientSecret,
+    token: storedToken,
+  }))).catch(() => 'error');
+
+  if ((status === 'disconnected' || status === 'error') && settings.removeInvalidTokens) {
+    await admin.firestore().doc(`users/${targetUid}`).update({
+      [`connections.${settings.provider}`]: FieldValue.delete(),
+      metadata: Manager.Metadata().set({ tag: 'user/connections' }),
+    });
+    ctx.log(`Removed invalid token for user: ${targetUid}`);
+  }
+
+  return ctx.respond({ status });
+}