Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

24.1 KB
Raw Blame
/**
 * Beeper connect flow (fork issue #31; decisions 2-4, 6 and 10 on #11).
 *
 * PortOS runs the OAuth flow ITSELF rather than asking the user for a token it
 * cannot mint. Beeper Desktop's `/.well-known/oauth-authorization-server`
 * advertises a `registration_endpoint`, `token_endpoint_auth_methods_supported:
 * ["none"]` and `code_challenge_methods_supported: ["S256"]`, so PortOS
 * registers as a PUBLIC client (no pre-shared secret) and runs
 * authorization_code + PKCE S256 with a `state` parameter. Both scopes are
 * requested in one authorization (`read write`): sending is in scope for the
 * product, and a second consent round-trip in the middle of composing a message
 * is worse than one prompt at setup.
 *
 * Pasting a token stays a FIRST-CLASS alternative, not a fallback. Nothing in
 * the OAuth surface accepts a lifetime — `/oauth/authorize`, `/oauth/token` and
 * `/oauth/register` take no expiry parameter and `expires_in` appears only as a
 * response field — while Beeper's own UI can mint a NO-EXPIRY token. There is
 * no `refresh_token` grant anywhere in the metadata, so an expired token is
 * re-connected, never refreshed. Both paths terminate in the same vaulted
 * credential (`beeperCredentials.js`).
 *
 * The token value never leaves this module except into the vault: it is never
 * logged, never put into an error message, and never returned to a route.
 *
 * Every path that changes whether a credential exists ends in
 * `reconcileBeeperIngestion()` — storing one arms the sweep and the realtime
 * transport without waiting for a restart, and a disconnect stops the relay
 * rather than leaving it running on a token that was just revoked.
 */

import { createHash, randomBytes } from 'crypto';
import { fetchWithTimeout } from '../lib/fetchWithTimeout.js';
import { readResponseJson } from '../lib/readResponseJson.js';
import { describeFetchError } from '../lib/fetchErrorChain.js';
import { isPlainObject } from '../lib/objects.js';
import {
  BeeperApiError, getAccounts, getInfo, probeBeeperInfo, resolveBeeperBaseUrl,
} from './beeperClient.js';
import { deleteBeeperCredential, readBeeperCredential, saveBeeperCredential } from './beeperCredentials.js';
import { reconcileBeeperIngestion } from './beeperArming.js';
import { updateSettingsWith } from './settings.js';
import { createFileWriteQueue } from '../lib/fileWriteQueue.js';

const METADATA_PATH = '/.well-known/oauth-authorization-server';
export const BEEPER_OAUTH_SCOPES = ['read', 'write'];
// Generous next to a live Beeper Desktop's 11-21 ms, and still short enough
// that a base URL pointing at a host that blackholes packets fails the connect
// action rather than hanging it. The 1 s liveness cap (#11 decision 5) is for
// the passive status probe, not for a user-initiated connect.
const OAUTH_TIMEOUT_MS = 10_000;
// An authorization the user never completes is garbage after this. Beeper's
// consent screen is local and takes seconds; ten minutes is slack, not a budget.
const PENDING_TTL_MS = 10 * 60 * 1000;

/**
 * In-flight authorizations, keyed by the `state` parameter: the PKCE verifier
 * that must never leave the server, plus the endpoints discovered when the flow
 * started (so the callback cannot be steered at a different token endpoint by a
 * base-URL change mid-flow). Module-level and in-memory on purpose — one server
 * process, one user, and a pending authorization that does not survive a
 * restart is correct: the user simply clicks Connect again.
 */
const pendingAuthorizations = new Map();
// Disconnect invalidates unfinished connects, including a token exchange already
// waiting on the network. Serialize only credential mutation and reconciliation
// so a save already underway finishes before disconnect removes it.
let connectionGeneration = 0;
const queueCredentialMutation = createFileWriteQueue();

function assertConnectionCurrent(generation) {
  if (generation !== connectionGeneration) {
    throw oauthError('This Beeper connection was cancelled — start the connect again', 'OAUTH_STATE_UNKNOWN', { status: 400 });
  }
}

function storeConnectedCredential(input, generation, reason) {
  return queueCredentialMutation(async () => {
    assertConnectionCurrent(generation);
    const saved = await saveBeeperCredential(input);
    await armIngestion(reason);
    return saved;
  });
}

function prunePending(now = Date.now()) {
  for (const [state, pending] of pendingAuthorizations) {
    if (now - pending.createdAt >= PENDING_TTL_MS) pendingAuthorizations.delete(state);
  }
}

const base64url = (buffer) => buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

/** RFC 7636 S256: `code_challenge = BASE64URL(SHA256(ASCII(code_verifier)))`. */
export function createPkcePair() {
  const codeVerifier = base64url(randomBytes(32));
  const codeChallenge = base64url(createHash('sha256').update(codeVerifier).digest());
  return { codeVerifier, codeChallenge };
}

function oauthError(message, code, { status = 502 } = {}) {
  return new BeeperApiError(message, { status, code, retryable: false });
}

// `localhost` and the loopback literals are the same host wearing different
// spellings — #11 decision 5 defaults the base URL to `127.0.0.1` precisely
// because a dual-stack box may resolve `localhost` to `::1` first, so treating
// them as different origins here would reject Beeper's own metadata.
const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
const sameHost = (a, b) => a === b || (LOOPBACK_HOSTS.has(a) && LOOPBACK_HOSTS.has(b));

/**
 * Resolve one advertised endpoint against the configured base URL, and refuse
 * one that points somewhere else. The metadata document is fetched from a
 * user-editable base URL (#30 makes it editable); without this check, whatever
 * answers on that URL could name any host as the token endpoint and PortOS
 * would POST the authorization code — and receive a token — off-box.
 *
 * Host and port are pinned for every base URL; SCHEME is pinned too UNLESS
 * both sides are loopback (SEC-3). Without that, metadata served from an
 * `https` base could name an `http` endpoint on the same host/port and
 * silently downgrade the token exchange to plaintext — same class of bug as
 * the OAuth redirect-origin check in `lib/beeperOAuthOrigin.js`, applied here
 * to the discovered endpoints instead of the browser-supplied origin. Loopback
 * still accepts a scheme mismatch: `resolveBeeperBaseUrl`'s own default is
 * `http://127.0.0.1:23373`, and a loopback connection carries no
 * network-path downgrade risk to defend against.
 */
function resolveEndpoint(value, baseUrl, field) {
  if (typeof value !== 'string' || !value.trim()) {
    throw oauthError(`Beeper authorization-server metadata is missing ${field}`, 'OAUTH_DISCOVERY_INVALID');
  }
  const base = new URL(baseUrl);
  const url = new URL(value.trim(), base);
  const bothLoopback = LOOPBACK_HOSTS.has(url.hostname) && LOOPBACK_HOSTS.has(base.hostname);
  if (
    !['http:', 'https:'].includes(url.protocol)
    || !sameHost(url.hostname, base.hostname)
    || url.port !== base.port
    || (!bothLoopback && url.protocol !== base.protocol)
  ) {
    throw oauthError(`Beeper authorization-server metadata points ${field} at a different host`, 'OAUTH_DISCOVERY_INVALID');
  }
  return url.toString();
}

async function fetchJson(url, init, { timeoutMs = OAUTH_TIMEOUT_MS } = {}) {
  let response;
  try {
    // A 307/308 can forward the token or PKCE verifier in the POST body to
    // another origin. Endpoint validation must also hold after the request.
    response = await fetchWithTimeout(url, { ...init, redirect: 'error' }, timeoutMs);
  } catch (err) {
    throw new BeeperApiError(`Beeper request failed: ${describeFetchError(err)}`, {
      status: 0, code: 'NETWORK_ERROR', retryable: false,
    });
  }
  const body = await readResponseJson(response, { fallback: (text) => ({ message: text }) });
  return { ok: response.ok, status: response.status, body };
}

/**
 * A live Beeper Desktop's metadata document (verified against 4.3.89) carries
 * twelve keys and no `introspection_endpoint` — the RFC 8414 field is
 * genuinely optional, and this server omits it, which makes the paste path's
 * introspection branch dead on every real install and every pasted token gets
 * stored with `expiresAt: null` / `scopes: []`, silencing the expiry warnings
 * `beeperStatus.tokenExpiryInfo` exists for. `GET /v1/info` advertises the
 * same endpoint at `endpoints.oauth.introspection_endpoint` instead
 * (live-verified), so this is the fallback discovery falls back to when the
 * metadata document is silent. It goes through the identical `resolveEndpoint`
 * same-host check as every other discovered endpoint — `/v1/info` is fetched
 * from the same user-editable base URL as the metadata document, so a value it
 * names still needs to be refused if it points elsewhere. A `/v1/info` that
 * fails outright (network error, malformed body) is not itself a discovery
 * failure — it just leaves introspection unavailable, same as if the metadata
 * document had said nothing at all, and `connectWithPastedToken` already falls
 * back to `verifyByAuthenticatedCall` for that case.
 *
 * `timeoutMs: OAUTH_TIMEOUT_MS` is deliberate — `getInfo`'s own default is
 * `DEFAULT_PROBE_TIMEOUT_MS` (1s), sized for the passive, frequently-polled
 * status card, not for a user-initiated connect/paste action that already
 * budgets 10s for every other request in this flow (`fetchJson` above).
 * Reusing the 1s probe cap here made this fallback fail under exactly the
 * kind of everyday local latency a live Beeper Desktop can show under load —
 * silently landing back on the no-expiry authenticated-call path this fix
 * exists to avoid.
 */
async function discoverIntrospectionEndpointFromInfo(resolvedBase) {
  let info;
  try {
    info = await getInfo({ baseUrl: resolvedBase, timeoutMs: OAUTH_TIMEOUT_MS });
  } catch {
    return null;
  }
  const value = info?.endpoints?.oauth?.introspection_endpoint;
  if (typeof value !== 'string' || !value.trim()) return null;
  return resolveEndpoint(value, resolvedBase, 'endpoints.oauth.introspection_endpoint');
}

/**
 * `GET /.well-known/oauth-authorization-server` on the configured base URL,
 * validated rather than trusted: every endpoint this flow uses must be present
 * and on the same host, and the server must advertise S256 when it advertises
 * anything at all (a server offering only `plain` would silently downgrade PKCE
 * to no protection).
 */
export async function discoverAuthorizationServer({ baseUrl } = {}) {
  const resolvedBase = baseUrl || await resolveBeeperBaseUrl();
  const { ok, status, body } = await fetchJson(`${resolvedBase}${METADATA_PATH}`, { method: 'GET' });
  if (!ok || !isPlainObject(body)) {
    throw oauthError(`Beeper authorization-server metadata unavailable (${status})`, 'OAUTH_DISCOVERY_FAILED');
  }
  const methods = body.code_challenge_methods_supported;
  if (Array.isArray(methods) && !methods.includes('S256')) {
    throw oauthError('Beeper authorization server does not support PKCE S256', 'OAUTH_DISCOVERY_INVALID');
  }
  // Optional: RFC 7662 introspection, which is how the paste path proves a
  // pasted token is real (see `connectWithPastedToken`). Falls back to
  // `/v1/info` when the metadata document omits it (see
  // `discoverIntrospectionEndpointFromInfo` above) — a live install commonly
  // does.
  const introspectionEndpoint = body.introspection_endpoint
    ? resolveEndpoint(body.introspection_endpoint, resolvedBase, 'introspection_endpoint')
    : await discoverIntrospectionEndpointFromInfo(resolvedBase);
  return {
    baseUrl: resolvedBase,
    authorizationEndpoint: resolveEndpoint(body.authorization_endpoint, resolvedBase, 'authorization_endpoint'),
    tokenEndpoint: resolveEndpoint(body.token_endpoint, resolvedBase, 'token_endpoint'),
    registrationEndpoint: resolveEndpoint(body.registration_endpoint, resolvedBase, 'registration_endpoint'),
    // Optional: "Disconnect" revokes when the server offers it, and merely
    // forgets when it does not.
    revocationEndpoint: body.revocation_endpoint
      ? resolveEndpoint(body.revocation_endpoint, resolvedBase, 'revocation_endpoint')
      : null,
    introspectionEndpoint,
  };
}

/**
 * RFC 7662 token introspection. Returns `{ active, expiresAt, scopes }` — the
 * only three fields this flow reads. `exp` is seconds since the epoch; absent
 * means the token does not expire, which is exactly the no-expiry credential
 * Beeper's own UI can mint, so it becomes `null` rather than a guessed default.
 *
 * `sub` is deliberately ignored: on this API it is an account identity, and
 * PortOS never stores or displays one.
 */
export async function introspectToken(token, { introspectionEndpoint, clientId } = {}) {
  const params = new URLSearchParams({ token });
  if (clientId) params.set('client_id', clientId);
  const { ok, status, body } = await fetchJson(introspectionEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      // Some deployments gate introspection on the token itself; sending it as
      // a bearer as well is harmless when they do not.
      Authorization: `Bearer ${token}`,
    },
    body: params.toString(),
  });
  if (!ok) {
    throw oauthError(`Beeper token introspection failed (HTTP ${status})`, 'OAUTH_INTROSPECTION_FAILED');
  }
  const exp = Number(body?.exp);
  return {
    active: body?.active === true,
    expiresAt: Number.isFinite(exp) && exp > 0 ? new Date(exp * 1000).toISOString() : null,
    scopes: typeof body?.scope === 'string' && body.scope.trim() ? body.scope.trim().split(/\s+/) : [],
  };
}

/**
 * RFC 7591 dynamic client registration as a PUBLIC client
 * (`token_endpoint_auth_method: 'none'`), which is what lets PortOS run this
 * flow with no pre-shared secret. Registration is per connect attempt: the
 * returned `client_id` is not a secret, costs one local round trip, and
 * re-registering keeps the redirect URI correct when the user reaches PortOS
 * over a different origin than last time.
 */
export async function registerOAuthClient({ registrationEndpoint, redirectUri, clientUri }) {
  const { ok, status, body } = await fetchJson(registrationEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_name: 'PortOS',
      ...(clientUri ? { client_uri: clientUri } : {}),
      grant_types: ['authorization_code'],
      response_types: ['code'],
      redirect_uris: [redirectUri],
      scope: BEEPER_OAUTH_SCOPES.join(' '),
      token_endpoint_auth_method: 'none',
    }),
  });
  const clientId = typeof body?.client_id === 'string' ? body.client_id.trim() : '';
  if (!ok || !clientId) {
    throw oauthError(`Beeper dynamic client registration failed (${status})`, 'OAUTH_REGISTRATION_FAILED');
  }
  return { clientId };
}

/**
 * Start a connect: discover, register, mint a PKCE pair plus `state`, and hand
 * back the authorization URL for the browser to open. The verifier stays here.
 */
export async function startBeeperOAuth({ redirectUri, clientUri } = {}) {
  if (typeof redirectUri !== 'string' || !redirectUri) {
    throw oauthError('A redirect URI is required to start the Beeper OAuth flow', 'OAUTH_REDIRECT_URI_MISSING', { status: 400 });
  }
  const generation = connectionGeneration;
  prunePending();
  const discovery = await discoverAuthorizationServer();
  const { clientId } = await registerOAuthClient({
    registrationEndpoint: discovery.registrationEndpoint, redirectUri, clientUri,
  });
  assertConnectionCurrent(generation);
  const { codeVerifier, codeChallenge } = createPkcePair();
  const state = base64url(randomBytes(24));
  pendingAuthorizations.set(state, {
    codeVerifier, clientId, redirectUri, createdAt: Date.now(), generation,
    tokenEndpoint: discovery.tokenEndpoint, baseUrl: discovery.baseUrl,
  });

  const params = new URLSearchParams({
    client_id: clientId,
    response_type: 'code',
    redirect_uri: redirectUri,
    state,
    scope: BEEPER_OAUTH_SCOPES.join(' '),
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
  });
  const separator = discovery.authorizationEndpoint.includes('?') ? '&' : '?';
  console.log(`🔗 Beeper OAuth authorization started (scopes=${BEEPER_OAUTH_SCOPES.join(' ')})`);
  return {
    authorizationUrl: `${discovery.authorizationEndpoint}${separator}${params.toString()}`,
    redirectUri,
    state,
  };
}

/** `expires_in` (seconds from now) → an absolute ISO instant, or null. */
export function expiryFromTokenResponse(body, now = Date.now()) {
  const seconds = Number(body?.expires_in);
  if (!Number.isFinite(seconds) || seconds <= 0) return null;
  return new Date(now + seconds * 1000).toISOString();
}

/**
 * Complete a connect: match `state` to its pending authorization, exchange the
 * code with the PKCE verifier, store the token + expiry in the vault, then
 * probe `/v1/info` so the caller learns whether Beeper Desktop is actually
 * answering. `state` is single-use — consumed before the exchange, so a replayed
 * callback cannot re-run it.
 *
 * `redirect_uri` is deliberately NOT sent on the exchange: the live
 * `/oauth/token` surface takes `grant_type, code, code_verifier, client_id`
 * (plus an optional `resource`) and nothing else.
 */
export async function completeBeeperOAuth({ code, state } = {}) {
  prunePending();
  const pending = state ? pendingAuthorizations.get(state) : null;
  if (!pending) {
    throw oauthError('This Beeper authorization has expired or was already used — start the connect again', 'OAUTH_STATE_UNKNOWN', { status: 400 });
  }
  pendingAuthorizations.delete(state);

  const { ok, status, body } = await fetchJson(pending.tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      code_verifier: pending.codeVerifier,
      client_id: pending.clientId,
    }).toString(),
  });
  const token = typeof body?.access_token === 'string' ? body.access_token.trim() : '';
  if (!ok || !token) {
    // `body.error` is the RFC 6749 error CODE (`invalid_grant`, …), never the
    // token — safe to surface. `error_description` is deliberately not
    // interpolated: it is free text from the authorization server.
    const reason = typeof body?.error === 'string' ? body.error : `HTTP ${status}`;
    throw oauthError(`Beeper token exchange failed (${reason})`, 'OAUTH_EXCHANGE_FAILED');
  }

  const scopes = typeof body.scope === 'string' && body.scope.trim()
    ? body.scope.trim().split(/\s+/)
    : BEEPER_OAUTH_SCOPES;
  const saved = await storeConnectedCredential({
    token,
    expiresAt: expiryFromTokenResponse(body),
    scopes,
    source: 'oauth',
    clientId: pending.clientId,
  }, pending.generation, 'oauth-connect');

  // Never throws (see beeperClient) — a token that stored fine while Beeper
  // Desktop happens to be closed is connected, not failed, and the status card
  // renders the unreachable state on its own.
  const probe = await probeBeeperInfo({ baseUrl: pending.baseUrl });
  return { ...saved, reachable: probe.reachable, lastProbeError: probe.error };
}

/**
 * The paste path (#11 decision 3). Beeper's own UI can mint a NO-EXPIRY token
 * and no OAuth parameter can request one, so this is a first-class alternative
 * rather than a fallback — and it terminates in the same vaulted credential.
 *
 * Validation must actually exercise the credential. `/v1/info` is Beeper's one
 * endpoint that ALSO answers unauthenticated, so probing it would happily
 * store a bogus token as connected. Instead:
 *
 *   1. RFC 7662 introspection when the authorization server advertises an
 *      `introspection_endpoint` — an inactive token is refused, and `exp`
 *      (absent for a no-expiry token) plus the returned scopes are stored.
 *   2. Otherwise `GET /v1/accounts`, which REQUIRES the bearer, so a rejected
 *      token surfaces here as a 401 instead of at first use. Nothing is known
 *      about its lifetime on this path, so the expiry is stored as `null`.
 *
 * Either way a token the server refuses is never written to the vault.
 */
export async function connectWithPastedToken(token) {
  const generation = connectionGeneration;
  const value = typeof token === 'string' ? token.trim() : '';
  if (!value) {
    throw oauthError('A Beeper access token is required', 'TOKEN_REQUIRED', { status: 400 });
  }
  const discovery = await discoverAuthorizationServer();
  const verified = discovery.introspectionEndpoint
    ? await verifyByIntrospection(value, discovery)
    : await verifyByAuthenticatedCall(value, discovery.baseUrl);

  const saved = await storeConnectedCredential({
    token: value, expiresAt: verified.expiresAt, scopes: verified.scopes, source: 'pasted',
  }, generation, 'token-pasted');
  return { ...saved, reachable: true, lastProbeError: null };
}

/**
 * Reconcile the sweep + realtime transport against the credential that just
 * changed. Isolated from the caller's verdict on purpose: the credential is
 * already stored (or already gone), so a reconcile that fails must not turn a
 * completed connect into a 500 — it is logged and the next trigger, or the next
 * restart, picks it up.
 */
async function armIngestion(reason) {
  await reconcileBeeperIngestion({ reason, restartSocket: true })
    .catch((err) => console.error(`❌ Beeper ingestion reconcile (${reason}) failed: ${err.message}`));
}

async function verifyByIntrospection(token, { introspectionEndpoint }) {
  const result = await introspectToken(token, { introspectionEndpoint });
  if (!result.active) {
    // Nothing about the token itself goes into the message — only the verdict.
    throw oauthError('Beeper rejected that access token (introspection reports it is not active)', 'TOKEN_REJECTED', { status: 401 });
  }
  return { expiresAt: result.expiresAt, scopes: result.scopes };
}

async function verifyByAuthenticatedCall(token, baseUrl) {
  // Throws UNAUTHORIZED on a rejected token and MALFORMED_RESPONSE when the
  // base URL points at something that answers 200 but isn't Beeper.
  await getAccounts({ baseUrl, token });
  return { expiresAt: null, scopes: [] };
}

/**
 * Disconnect. Best-effort revocation first (#11 decision 2: "Disconnect calls
 * `/oauth/revoke` rather than merely deleting the local copy"), then the local
 * delete — which runs whether or not revocation worked, because a user asking
 * to disconnect must always end up disconnected. A pasted token has no
 * registered client to revoke against, so it is only forgotten.
 */
export function disconnectBeeper() {
  connectionGeneration += 1;
  pendingAuthorizations.clear();
  return queueCredentialMutation(disconnectCredential);
}

async function disconnectCredential() {
  const credential = await readBeeperCredential().catch(() => null);
  if (credential?.tokenSource === 'oauth' && credential.clientId) {
    const revoked = await revokeToken(credential).catch((err) => ({ revoked: false, error: err?.message }));
    console.log(revoked?.revoked
      ? '🔓 Beeper token revoked at the authorization server'
      : '⚠️ Beeper token revocation was not accepted; deleting the local copy anyway');
  }
  // Clear the supported legacy fallback before deleting the vault entry;
  // otherwise the resolver resurrects that credential and re-arms ingestion.
  await updateSettingsWith((settings) => {
    if (!isPlainObject(settings.beeper)) return settings;
    const { token, tokenExpiresAt, ...beeper } = settings.beeper;
    return { ...settings, beeper };
  });
  const result = await deleteBeeperCredential();
  // The credential is gone, so the gate is now shut: stop the relay rather than
  // leaving a live WebSocket running on a token the user just revoked.
  await armIngestion('disconnect');
  return result;
}

async function revokeToken({ token, clientId }) {
  const discovery = await discoverAuthorizationServer();
  if (!discovery.revocationEndpoint) return { revoked: false };
  const { ok } = await fetchJson(discovery.revocationEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ token, client_id: clientId }).toString(),
  });
  return { revoked: ok };
}

/** Test seam: forget every pending authorization between cases. */
export function __resetPendingAuthorizationsForTests() {
  pendingAuthorizations.clear();
}