@omega.js/backend 0.1.0

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

@@ -0,0 +1,247 @@
+/**
+ * The steps a connection is made of, and the ONE context every one of them is
+ * called with ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)).
+ *
+ * A provider module declares data (`urls`, `scope`, `params`, `pkce`) and, for
+ * anything the data cannot say, a function. Every function — the provider's own
+ * or the default below — is called as a METHOD on the module (`this.urls.*`
+ * keeps working) and receives the same object:
+ *
+ *   { provider, providerName, Manager, ctx, uid, clientId, clientSecret,
+ *     redirectUri, scope, state, pkce, code, token, fetch }
+ *
+ * `pkce` is `{ verifier, challenge }` when the provider declares `pkce: 'S256'`
+ * and null otherwise; `code` is the authorization code (exchange); `token` is
+ * the exchange RESPONSE for `identity` and the STORED record for `refresh`,
+ * `revoke` and `status`. `fetch` is the lane's HTTP call, handed in so a step
+ * has ONE seam.
+ *
+ * One concern, one file: nothing here reads the environment or loads a module.
+ */
+
+const fetch = require('wonderful-fetch');
+const { arrayify } = require('node-powertools');
+
+// How long the REFRESH step may spend at the provider
+// ([#783](https://github.com/Omega-JS-Stack/omega/issues/783)). It is shorter
+// than the exchange's 60s on purpose: a refresh runs while holding the lease in
+// `_lease.js`, and a call that outlived the lease would let a second caller
+// reclaim it and spend the same one-time refresh token. That file asserts the
+// relationship at load, reading THIS constant, so the two can never drift.
+const REFRESH_TIMEOUT_MS = 20000;
+
+// What the default `revoke` answers for a provider that declares no
+// `urls.revoke`: there is nothing to call, the record is still deleted, and the
+// route says which of the two happened
+const REVOKE_UNSUPPORTED = 'unsupported';
+
+/**
+ * The one context object every step is called with — the ONE home of its shape.
+ * Keys the step at hand has no use for are present and undefined, so a provider
+ * author reads one table and never wonders which call site they are in.
+ *
+ * @param {object} parts - Whatever the route resolved
+ * @returns {object} The step context
+ */
+function buildGrantContext({
+  provider,
+  providerName,
+  Manager,
+  ctx,
+  uid,
+  clientId,
+  clientSecret,
+  redirectUri,
+  scope,
+  state,
+  pkce,
+  code,
+  token,
+}) {
+  return {
+    provider,
+    providerName,
+    Manager,
+    ctx,
+    uid,
+    clientId,
+    clientSecret,
+    redirectUri,
+    scope,
+    state,
+    pkce: pkce || null,
+    code,
+    token,
+    fetch,
+  };
+}
+
+/**
+ * The authorization URL a redirect flow sends the user to.
+ *
+ * @param {object} context - The step context
+ * @returns {string} The authorization URL
+ */
+function defaultAuthorize(context) {
+  const { provider, clientId, redirectUri, scope, state, pkce } = context;
+
+  const url = new URL(provider.urls.authorize);
+
+  url.searchParams.set('state', state);
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('scope', arrayify(scope).join(' '));
+
+  // Provider-specific authorize params
+  for (const [key, value] of Object.entries(provider.params || {})) {
+    url.searchParams.set(key, value);
+  }
+
+  // PKCE: the challenge travels, the verifier never does
+  if (pkce) {
+    url.searchParams.set('code_challenge', pkce.challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+  }
+
+  return url.toString();
+}
+
+/**
+ * Exchange the authorization code for tokens.
+ *
+ * @param {object} context - The step context
+ * @returns {Promise<object>} The token response
+ */
+function defaultExchange(context) {
+  const { provider, clientId, clientSecret, redirectUri, code, pkce, fetch: call } = context;
+
+  const body = {
+    client_id: clientId,
+    // A PUBLIC client has no secret to send
+    // ([#785](https://github.com/Omega-JS-Stack/omega/issues/785)): Twitch (and
+    // any OAuth 2.1 provider) registers one, the brand holds an id alone, and an
+    // EMPTY `client_secret` is not the same request as no `client_secret` — the
+    // token endpoint reads the field as a wrong secret and refuses the grant.
+    // The key is omitted when the `CONNECTIONS_<PROVIDER>_CLIENT_SECRET` key is
+    // unset or empty; a confidential client's body is unchanged, field for field.
+    ...(clientSecret ? { client_secret: clientSecret } : {}),
+    grant_type: 'authorization_code',
+    redirect_uri: redirectUri,
+    code: code,
+  };
+
+  if (pkce) {
+    body.code_verifier = pkce.verifier;
+  }
+
+  return call(provider.urls.token, {
+    method: 'POST',
+    timeout: 60000,
+    response: 'json',
+    body: new URLSearchParams(body),
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  });
+}
+
+/**
+ * Refresh an access token from the stored record.
+ *
+ * @param {object} context - The step context
+ * @returns {Promise<object>} The token response
+ */
+function defaultRefresh(context) {
+  const { provider, clientId, clientSecret, token, fetch: call } = context;
+
+  const body = {
+    client_id: clientId,
+    // Omitted for a public client, exactly as in the exchange above
+    // ([#785](https://github.com/Omega-JS-Stack/omega/issues/785))
+    ...(clientSecret ? { client_secret: clientSecret } : {}),
+    grant_type: 'refresh_token',
+    refresh_token: token.refresh_token,
+  };
+
+  return call(provider.urls.token, {
+    method: 'POST',
+    timeout: REFRESH_TIMEOUT_MS,
+    response: 'json',
+    body: new URLSearchParams(body),
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  });
+}
+
+/**
+ * Revoke the access token at the provider — RFC 7009: a form POST carrying the
+ * token, plus the client credentials the provider knows this app by.
+ *
+ * A provider that declares no `urls.revoke` cannot revoke at all (Spotify), and
+ * says so rather than pretending: the answer is `'unsupported'`, and the delete
+ * removes the record either way. Every other outcome is silence (revoked) or a
+ * throw (the route reports it and still deletes).
+ *
+ * @param {object} context - The step context (`token` is the stored record)
+ * @returns {Promise<string|undefined>} `'unsupported'`, or nothing
+ */
+async function defaultRevoke(context) {
+  const { provider, clientId, clientSecret, token, fetch: call } = context;
+
+  if (!provider.urls?.revoke) {
+    return REVOKE_UNSUPPORTED;
+  }
+
+  await call(provider.urls.revoke, {
+    method: 'POST',
+    timeout: 60000,
+    body: new URLSearchParams({
+      token: token.access_token,
+      ...(clientId ? { client_id: clientId } : {}),
+      ...(clientSecret ? { client_secret: clientSecret } : {}),
+    }),
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  });
+}
+
+// The steps the lane can run without the provider's help. `identity` is not
+// here: nothing can guess whose account a token belongs to, which is why
+// assertProviderShape requires it. Neither is `status`: without one, a stored
+// refresh token IS the answer.
+const GRANT_DEFAULTS = {
+  authorize: defaultAuthorize,
+  exchange: defaultExchange,
+  refresh: defaultRefresh,
+  revoke: defaultRevoke,
+};
+
+/**
+ * Run one step: the provider's own function when it declares one, else the
+ * default — always as a method on the module.
+ *
+ * @param {object} provider - The provider module
+ * @param {'authorize'|'exchange'|'identity'|'refresh'|'revoke'|'status'} step - The step to run
+ * @param {object} context - The step context
+ * @returns {*} Whatever the step answers (a URL string, a token response, an identity)
+ * @throws {Error} When the step has neither an override nor a default
+ */
+function runStep(provider, step, context) {
+  const fn = typeof provider[step] === 'function' ? provider[step] : GRANT_DEFAULTS[step];
+
+  if (typeof fn !== 'function') {
+    // A programmer error: the route asked for a step this provider cannot run
+    // and the lane has no default for. Loud here beats a TypeError at the seam.
+    throw new Error(`Connection provider ${provider.provider} declares no ${step}() and the lane has no default for it`);
+  }
+
+  return fn.call(provider, context);
+}
+
+module.exports = {
+  REFRESH_TIMEOUT_MS,
+  REVOKE_UNSUPPORTED,
+  buildGrantContext,
+  defaultAuthorize,
+  defaultExchange,
+  defaultRefresh,
+  defaultRevoke,
+  runStep,
+};

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

@@ -0,0 +1,184 @@
+const crypto = require('crypto');
+const { FieldValue } = require('firebase-admin/firestore');
+const { REFRESH_TIMEOUT_MS } = require('./_grant.js');
+
+// ============================================================================
+// The refresh lease ([#783](https://github.com/Omega-JS-Stack/omega/issues/783))
+//
+// A backend never runs as one process: Cloud Functions scales to as many
+// instances as the traffic asks for, and two of them refreshing the SAME user's
+// SAME provider at once spend a one-time refresh token twice (Twitch rotates
+// its own on every use). The loser's exchange is refused and the token it stores
+// is dead. A per-process lock cannot see the other instance; Firestore can, so
+// the lease is a NOTE ON THE RECORD, taken in a transaction.
+//
+// It lives beside the route helpers rather than inside post.js so `delete` can
+// take the same lease later — revoking under a running refresh is the same race.
+// ============================================================================
+
+// A lease older than this is STALE and anybody may take it: an instance that
+// crashed mid-refresh (or was evicted) never runs its own clear, and a record
+// that stayed leased forever would refuse every later refresh.
+const LEASE_TTL_SECONDS = 30;
+
+// How the loser waits for the winner's write: re-read every POLL, give up after WAIT.
+const LEASE_POLL_MS = 500;
+const LEASE_WAIT_MS = 10000;
+
+// The lease has to OUTLIVE the call it protects. The winner holds it across the
+// provider's refresh POST, and that call has its own timeout: if the timeout were
+// the longer of the two, a slow provider would let the lease expire under a
+// running refresh, a second caller would win it, and both would spend the same
+// one-time refresh token — exactly the race the lease exists to stop. So the
+// relationship is asserted here, at load, against the one home of the timeout:
+// a programmer changing either number learns at boot, not from a dead token in
+// production.
+if (LEASE_TTL_SECONDS * 1000 <= REFRESH_TIMEOUT_MS) {
+  throw new Error(`Connections refresh lease: LEASE_TTL_SECONDS (${LEASE_TTL_SECONDS}s) must exceed the refresh step's REFRESH_TIMEOUT_MS (${REFRESH_TIMEOUT_MS}ms) — a lease that expires under a running refresh lets a second caller spend the same one-time refresh token`);
+}
+
+// ONE id per process, minted at module load: the lease says which instance holds
+// it, so a stalled refresh is nameable in a log and in the 409 a loser answers.
+const INSTANCE_ID = crypto.randomBytes(8).toString('hex');
+
+/**
+ * The stored connection record, whatever the document is missing.
+ *
+ * @param {object} snapshot - A Firestore document snapshot
+ * @param {string} provider - The provider key
+ * @returns {object} The record, or {}
+ */
+function connectionRecord(snapshot, provider) {
+  return (snapshot.data() || {}).connections?.[provider] || {};
+}
+
+/**
+ * Take the refresh lease on `users/<uid>.connections.<provider>`, in a
+ * transaction so two instances reading the same absent lease cannot both write
+ * one.
+ *
+ * The caller that WINS runs the provider refresh and is the one that clears the
+ * lease (in its own write, or through clearRefreshLease() when it fails). The
+ * caller that LOSES touches the provider not at all — it waits for the winner's
+ * token with awaitRefreshedToken().
+ *
+ * @param {object} options
+ * @param {object} options.admin - The firebase-admin library (the route's own handle)
+ * @param {string} options.uid - The user the connection belongs to
+ * @param {string} options.provider - The provider key
+ * @returns {Promise<{won: boolean, lease: object, updatedUNIX: number, token: object|undefined}>}
+ *   Whether this caller holds the lease, the lease note (this caller's, or the
+ *   holder's when it lost), the `updated.timestampUNIX` the record carried at
+ *   entry — the value a loser watches for movement past — and the stored token
+ *   AS THE TRANSACTION SAW IT, which is the one a winner refreshes with
+ */
+async function acquireRefreshLease({ admin, uid, provider }) {
+  const firestore = admin.firestore();
+  const docRef = firestore.doc(`users/${uid}`);
+
+  return firestore.runTransaction(async (transaction) => {
+    const snapshot = await transaction.get(docRef);
+    const record = connectionRecord(snapshot, provider);
+
+    const nowMs = Date.now();
+    const nowUNIX = Math.floor(nowMs / 1000);
+    const updatedUNIX = record.updated?.timestampUNIX || 0;
+    const held = record.refreshing;
+
+    if (held && nowUNIX - (held.timestampUNIX || 0) < LEASE_TTL_SECONDS) {
+      return { won: false, lease: held, updatedUNIX, token: record.token };
+    }
+
+    const lease = {
+      instance: INSTANCE_ID,
+      timestamp: new Date(nowMs).toISOString(),
+      timestampUNIX: nowUNIX,
+    };
+
+    transaction.set(docRef, {
+      connections: { [provider]: { refreshing: lease } },
+    }, { merge: true });
+
+    return { won: true, lease, updatedUNIX, token: record.token };
+  });
+}
+
+/**
+ * Drop the lease without touching anything else — the FAILURE path of a winner
+ * (the success path removes it in the same write that stores the token, so the
+ * record is never one write away from consistent).
+ *
+ * @param {object} options
+ * @param {object} options.admin - The firebase-admin library
+ * @param {string} options.uid - The user the connection belongs to
+ * @param {string} options.provider - The provider key
+ * @returns {Promise<void>}
+ */
+async function clearRefreshLease({ admin, uid, provider }) {
+  await admin.firestore().doc(`users/${uid}`).set({
+    connections: { [provider]: { refreshing: FieldValue.delete() } },
+  }, { merge: true });
+}
+
+/**
+ * Wait for the caller that WON the lease to finish. A loser runs no grant step at
+ * all: the refresh token is one-time, and the winner is already spending it.
+ *
+ * The wait has THREE outcomes, and only one of them is a token:
+ *
+ *   - `refreshed` — `updated.timestampUNIX` moved past what it was at entry. The
+ *     winner wrote, and the record now holds a token this caller can answer with.
+ *   - `abandoned` — the note is gone but the stamp never moved: the winner's
+ *     provider call failed (or its lease expired) and the stored token is the
+ *     PRE-refresh one. Answering it as a success would hand a caller a token that
+ *     may be expired, and a rotating provider may already have invalidated it, so
+ *     this is a conflict to report — never a token to return.
+ *   - `timeout` — neither happened inside the window.
+ *
+ * `pollMs`/`timeoutMs` are the contract above, as parameters so the offline case
+ * can drive a timeout without waiting ten real seconds.
+ *
+ * @param {object} options
+ * @param {object} options.admin - The firebase-admin library
+ * @param {string} options.uid - The user the connection belongs to
+ * @param {string} options.provider - The provider key
+ * @param {number} options.since - The `updated.timestampUNIX` seen at entry
+ * @param {number} [options.pollMs] - Milliseconds between reads
+ * @param {number} [options.timeoutMs] - Milliseconds before giving up
+ * @returns {Promise<{outcome: 'refreshed'|'abandoned'|'timeout', token: object|null}>}
+ *   The outcome, and the stored token on `refreshed` alone
+ */
+async function awaitRefreshedToken({ admin, uid, provider, since, pollMs = LEASE_POLL_MS, timeoutMs = LEASE_WAIT_MS }) {
+  const docRef = admin.firestore().doc(`users/${uid}`);
+  const startTime = Date.now();
+
+  while (true) {
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+
+    const record = connectionRecord(await docRef.get(), provider);
+
+    // The winner writes the token, the stamp and the note's removal in ONE
+    // write, so a moved stamp is checked first: it is the only success
+    if ((record.updated?.timestampUNIX || 0) > since) {
+      return { outcome: 'refreshed', token: record.token || null };
+    }
+
+    if (!record.refreshing) {
+      return { outcome: 'abandoned', token: null };
+    }
+
+    if (Date.now() - startTime >= timeoutMs) {
+      return { outcome: 'timeout', token: null };
+    }
+  }
+}
+
+module.exports = {
+  INSTANCE_ID,
+  LEASE_TTL_SECONDS,
+  LEASE_POLL_MS,
+  LEASE_WAIT_MS,
+  acquireRefreshLease,
+  clearRefreshLease,
+  awaitRefreshedToken,
+};

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

@@ -0,0 +1,191 @@
+/**
+ * Provider modules: where they are found, whether they can run a grant, and the
+ * credentials the brand registered them with
+ * ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)).
+ *
+ * One concern, one file: nothing here knows what a grant step does, what the
+ * state cipher is, or which user the route is acting on.
+ */
+
+const path = require('path');
+const jetpack = require('fs-jetpack');
+// Aliased: this file exports its OWN loadProvider (the connection lookup below)
+const loadProviderModule = require('../../../libraries/load-provider.js');
+const providerPath = loadProviderModule.providerPath;
+const env = require('../../../libraries/env.js');
+
+const PROVIDERS_DIR = path.join(__dirname, 'providers');
+
+// A brand's own providers, staged with the rest of its src/
+// ([#771](https://github.com/Omega-JS-Stack/omega/issues/771)): the same
+// `${Manager.cwd}/<dir>/<name>.js` convention `src/routes/` and the event
+// handlers already use, and it is searched FIRST — a brand may replace a
+// packaged provider by shipping a file with its name.
+const BRAND_PROVIDERS_DIR = 'connections';
+
+/**
+ * The directories a provider name is looked up in, in order: the brand's own
+ * staged `connections/` dir, then the package's.
+ *
+ * @param {object|null} Manager - The BackendManager (its `cwd` is the staged consumer dir)
+ * @returns {string[]} Absolute directory paths, brand first
+ */
+function providerDirs(Manager) {
+  const dirs = [];
+
+  if (Manager && Manager.cwd) {
+    dirs.push(path.join(Manager.cwd, BRAND_PROVIDERS_DIR));
+  }
+
+  dirs.push(PROVIDERS_DIR);
+
+  return dirs;
+}
+
+/**
+ * A provider module that cannot run its grant is a PROGRAMMER error, not a
+ * caller's typo: it throws here, naming the file and the field, instead of
+ * failing at the redirect or the token exchange with the provider's own
+ * opaque message ([#771](https://github.com/Omega-JS-Stack/omega/issues/771)).
+ *
+ * The three requirements are the three things the lane cannot invent
+ * ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)): where the user
+ * is sent, how the code becomes a token, and who the token belongs to. Every
+ * other step has a default.
+ *
+ * The message names the FILE, never the path it was found at: the request that
+ * tripped it belongs to a signed-in user, and where a brand's code is deployed
+ * is not theirs to read. The file name is what a developer needs anyway.
+ *
+ * @param {*} provider - The required module
+ * @param {string} filePath - The file it came from
+ * @returns {object} The same module
+ * @throws {Error} When the module cannot answer an authorize, an exchange or an identity
+ */
+function assertProviderShape(provider, filePath) {
+  const file = path.basename(filePath);
+
+  if (!provider || typeof provider !== 'object') {
+    throw new Error(`Connection provider ${file} must export an object (the module shape: provider, name, urls, scope, identity)`);
+  }
+
+  if (!provider.urls?.authorize && typeof provider.authorize !== 'function') {
+    throw new Error(`Connection provider ${file} declares no urls.authorize and no authorize() — one of the two has to say where the user is sent`);
+  }
+
+  if (!provider.urls?.token && typeof provider.exchange !== 'function') {
+    throw new Error(`Connection provider ${file} declares no urls.token and no exchange() — one of the two has to say how the code becomes a token`);
+  }
+
+  if (typeof provider.identity !== 'function') {
+    throw new Error(`Connection provider ${file} declares no identity() — the lane cannot know whose account a token belongs to`);
+  }
+
+  if (provider.pkce && provider.pkce !== 'S256') {
+    throw new Error(`Connection provider ${file} declares pkce: '${provider.pkce}' — S256 is the only challenge method the lane mints`);
+  }
+
+  return provider;
+}
+
+/**
+ * Resolve a provider module by name: the brand's own file wins, the package's
+ * answers otherwise, and a name nothing answers is null (the caller's 400).
+ *
+ * @param {string} providerName - The provider key ('google', 'twitch', …)
+ * @param {object|null} Manager - The BackendManager
+ * @returns {object|null} The provider module, or null when no file exists
+ * @throws {Error} When a file exists but exports a malformed shape
+ */
+function resolveProvider(providerName, Manager) {
+  for (const dir of providerDirs(Manager)) {
+    let file;
+
+    try {
+      file = providerPath(dir, providerName);
+    } catch (e) {
+      // An invalid name can never name a file: it is an unknown provider, and
+      // the confined loader is what decided that (never a second copy of the rule)
+      return null;
+    }
+
+    if (jetpack.exists(file) !== 'file') {
+      continue;
+    }
+
+    return assertProviderShape(loadProviderModule(dir, providerName), file);
+  }
+
+  return null;
+}
+
+/**
+ * The credential pair a provider was registered with — the ONE home of the env
+ * key convention ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)):
+ * the provider name uppercased, dashes as underscores.
+ *
+ * A public client has no secret ([#785](https://github.com/Omega-JS-Stack/omega/issues/785)),
+ * and an unset key resolves to nothing rather than an empty string the grant
+ * would send.
+ *
+ * @param {string} providerName - The provider key
+ * @returns {{ clientId: string|undefined, clientSecret: string|undefined }}
+ */
+function providerCredentials(providerName) {
+  const providerEnvKey = providerName.toUpperCase().replace(/-/g, '_');
+
+  return {
+    clientId: env.get(`CONNECTIONS_${providerEnvKey}_CLIENT_ID`),
+    clientSecret: env.get(`CONNECTIONS_${providerEnvKey}_CLIENT_SECRET`),
+  };
+}
+
+/**
+ * Load a provider and its credentials, or the 400 an unknown name answers.
+ *
+ * @param {string} providerName - The provider key
+ * @param {object|null} Manager - The BackendManager
+ * @returns {object} `{ connectionProvider, clientId, clientSecret }` or `{ error }`
+ */
+function loadProvider(providerName, Manager) {
+  const connectionProvider = resolveProvider(providerName, Manager);
+
+  if (!connectionProvider) {
+    return { error: { message: `Unknown connection provider: ${providerName}`, code: 400 } };
+  }
+
+  return { connectionProvider, ...providerCredentials(providerName) };
+}
+
+/**
+ * The ONE line a provider's identity step may log
+ * ([#641](https://github.com/Omega-JS-Stack/omega/issues/641)).
+ *
+ * Every provider used to hand `ctx.log` the token exchange RESPONSE, which
+ * carries the access token, the refresh token and (Google) the id token — so a
+ * brand's Cloud Logging held live third-party credentials for the whole
+ * retention window, readable by anyone with a log-viewer role. The decoded
+ * profile and the provider's identity response went the same way, and those are
+ * the user's PII.
+ *
+ * What a log needs is WHICH provider, WHOSE account, and whether the exchange
+ * came back with a token. Nothing on this line is a credential or a person, and
+ * one home for the format keeps the providers from drifting apart.
+ *
+ * @param {object} ctx - The route context (the log sink)
+ * @param {object} options
+ * @param {string} options.provider - The provider key ('google', 'discord', …)
+ * @param {string|null} [options.uid] - The account the identity is being linked to
+ * @param {object} [options.token] - The token exchange response — READ for whether
+ *   it succeeded, never logged
+ */
+function logIdentityCheck(ctx, { provider, uid, token }) {
+  ctx.log(`identity(): provider=${provider}, uid=${uid || 'null'}, tokenExchange=${token?.access_token ? 'succeeded' : 'failed'}`);
+}
+
+module.exports = {
+  assertProviderShape,
+  resolveProvider,
+  loadProvider,
+  logIdentityCheck,
+};