@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.200

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth-client.ts

@@ -0,0 +1,159 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { whyUnreachable } from './reach.js';
+import { refused, type OAuthTokens } from './verify.js';
+import type { OAuthServer } from './oauth-discovery.js';
+import { isRecord } from '@metro-labs/core/is-record';
+
+const TOKEN_TIMEOUT_MS = 15_000;
+const CLIENT_NAME = 'Metro';
+
+export interface OAuthClient {
+  clientId: string;
+  clientSecret?: string;
+}
+
+export function newVerifier(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+export function challengeOf(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+export async function registerClient(
+  server: OAuthServer,
+  redirectUri: string,
+): Promise<OAuthClient> {
+  if (server.registrationEndpoint === null)
+    throw refused(
+      'That server signs in with OAuth but registers no clients on its own. ' +
+        `Register an app with it yourself, with ${redirectUri} as its redirect URL, ` +
+        "and add the connector again with that app's client ID.",
+    );
+  let res: Response;
+  try {
+    res = await fetch(server.registrationEndpoint, {
+      method: 'POST',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({
+        client_name: CLIENT_NAME,
+        redirect_uris: [redirectUri],
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+      }),
+    });
+  } catch (err) {
+    throw refused(`Metro could not reach that server to register: ${whyUnreachable(err)}`);
+  }
+  const body: unknown = await res.json().catch(() => null);
+  if (!res.ok || !isRecord(body) || typeof body.client_id !== 'string')
+    throw refused('That server refused to register Metro as a client.');
+  const secret = body.client_secret;
+  return {
+    clientId: body.client_id,
+    ...(typeof secret === 'string' ? { clientSecret: secret } : {}),
+  };
+}
+
+export interface AuthorizeInput {
+  server: OAuthServer;
+  client: OAuthClient;
+  redirectUri: string;
+  state: string;
+  verifier: string;
+  resource: string;
+}
+
+export function authorizeUrl(input: AuthorizeInput): string {
+  const url = new URL(input.server.authorizationEndpoint);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', input.client.clientId);
+  url.searchParams.set('redirect_uri', input.redirectUri);
+  url.searchParams.set('state', input.state);
+  url.searchParams.set('code_challenge', challengeOf(input.verifier));
+  url.searchParams.set('code_challenge_method', 'S256');
+  url.searchParams.set('resource', input.resource);
+  if (input.server.scopes.length > 0)
+    url.searchParams.set('scope', input.server.scopes.join(' '));
+  return url.toString();
+}
+
+function tokensFrom(body: Record<string, unknown>): OAuthTokens {
+  const access = body.access_token;
+  if (typeof access !== 'string' || access === '')
+    throw refused('That server did not return an access token.');
+  const refresh = body.refresh_token;
+  const expires = body.expires_in;
+  return {
+    accessToken: access,
+    ...(typeof refresh === 'string' ? { refreshToken: refresh } : {}),
+    ...(typeof expires === 'number'
+      ? { expiresAt: Date.now() + expires * 1000 }
+      : {}),
+  };
+}
+
+async function postToken(
+  server: OAuthServer,
+  client: OAuthClient,
+  form: Record<string, string>,
+): Promise<OAuthTokens> {
+  const params = new URLSearchParams({
+    ...form,
+    client_id: client.clientId,
+    ...(client.clientSecret === undefined
+      ? {}
+      : { client_secret: client.clientSecret }),
+  });
+  let res: Response;
+  try {
+    res = await fetch(server.tokenEndpoint, {
+      method: 'POST',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        accept: 'application/json',
+      },
+      body: params.toString(),
+    });
+  } catch (err) {
+    throw refused(`Metro could not reach that server to finish signing in: ${whyUnreachable(err)}`);
+  }
+  const body: unknown = await res.json().catch(() => null);
+  if (!res.ok || !isRecord(body))
+    throw refused('That server refused to complete the sign-in.');
+  return tokensFrom(body);
+}
+
+export function exchangeCode(
+  server: OAuthServer,
+  client: OAuthClient,
+  input: { code: string; redirectUri: string; verifier: string; resource: string },
+): Promise<OAuthTokens> {
+  return postToken(server, client, {
+    grant_type: 'authorization_code',
+    code: input.code,
+    redirect_uri: input.redirectUri,
+    code_verifier: input.verifier,
+    resource: input.resource,
+  });
+}
+
+export function refreshTokens(
+  server: OAuthServer,
+  client: OAuthClient,
+  refreshToken: string,
+  resource: string,
+  scope?: string,
+): Promise<OAuthTokens> {
+  return postToken(server, client, {
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    resource,
+    ...(scope === undefined ? {} : { scope }),
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth-discovery.ts

@@ -0,0 +1,135 @@
+import { parseConnectorUrl, refused } from './verify.js';
+import { isRecord } from '@metro-labs/core/is-record';
+
+const DISCOVERY_TIMEOUT_MS = 10_000;
+
+export interface OAuthServer {
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint: string | null;
+  supportsS256: boolean;
+  scopes: string[];
+}
+
+interface ResourceMetadata {
+  issuer: URL;
+  scopes: string[];
+}
+
+const str = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+async function getJson(url: URL): Promise<Record<string, unknown> | null> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      redirect: 'manual',
+      signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) {
+    await res.body?.cancel().catch(() => undefined);
+    return null;
+  }
+  const body: unknown = await res.json().catch(() => null);
+  return isRecord(body) ? body : null;
+}
+
+function wellKnown(base: URL, suffix: string): URL {
+  const url = new URL(base.toString());
+  url.pathname = `/.well-known/${suffix}`;
+  url.search = '';
+  url.hash = '';
+  return url;
+}
+
+export function resourceMetadataUrls(resource: URL): URL[] {
+  const path = resource.pathname.replace(/\/$/, '');
+  const urls = [wellKnown(resource, 'oauth-protected-resource')];
+  if (path !== '')
+    urls.unshift(
+      new URL(`/.well-known/oauth-protected-resource${path}`, resource.origin),
+    );
+  return urls;
+}
+
+export async function advertisesOAuth(resource: URL): Promise<boolean> {
+  for (const candidate of resourceMetadataUrls(resource)) {
+    const body = await getJson(candidate);
+    const servers: unknown = body?.authorization_servers;
+    const first: unknown = Array.isArray(servers) ? servers[0] : undefined;
+    if (typeof first === 'string' && first !== '') return true;
+  }
+  return false;
+}
+
+function scopesOf(body: Record<string, unknown> | null): string[] {
+  const raw: unknown = body?.scopes_supported;
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    const scope = str(entry).trim();
+    if (scope !== '' && !/\s/.test(scope) && !out.includes(scope)) out.push(scope);
+  }
+  return out;
+}
+
+async function resourceMetadata(resource: URL): Promise<ResourceMetadata> {
+  for (const candidate of resourceMetadataUrls(resource)) {
+    const body = await getJson(candidate);
+    const servers: unknown = body?.authorization_servers;
+    const first: unknown = Array.isArray(servers) ? servers[0] : undefined;
+    if (typeof first === 'string' && first !== '')
+      return { issuer: parseConnectorUrl(first), scopes: scopesOf(body) };
+  }
+  return { issuer: parseConnectorUrl(resource.origin), scopes: [] };
+}
+
+function toServer(
+  body: Record<string, unknown>,
+  issuer: URL,
+  scopes: string[],
+): OAuthServer {
+  const authorizationEndpoint = str(body.authorization_endpoint);
+  const tokenEndpoint = str(body.token_endpoint);
+  if (authorizationEndpoint === '' || tokenEndpoint === '')
+    throw refused(
+      `${issuer.hostname} advertises OAuth but not where to sign in.`,
+    );
+  const methods = body.code_challenge_methods_supported;
+  const registration = str(body.registration_endpoint);
+  return {
+    issuer: str(body.issuer) === '' ? issuer.origin : str(body.issuer),
+    authorizationEndpoint,
+    tokenEndpoint,
+    registrationEndpoint: registration === '' ? null : registration,
+    supportsS256: Array.isArray(methods) ? methods.includes('S256') : false,
+    scopes,
+  };
+}
+
+export function authServerMetadataUrls(issuer: URL): URL[] {
+  const path = issuer.pathname.replace(/\/$/, '');
+  const suffixes = ['oauth-authorization-server', 'openid-configuration'];
+  const urls = suffixes.map((suffix) => wellKnown(issuer, suffix));
+  if (path === '') return urls;
+  const aware = suffixes.map(
+    (suffix) => new URL(`/.well-known/${suffix}${path}`, issuer.origin),
+  );
+  return [...aware, new URL(`${path}/.well-known/openid-configuration`, issuer.origin), ...urls];
+}
+
+export async function discoverOAuth(resource: URL): Promise<OAuthServer> {
+  const { issuer, scopes } = await resourceMetadata(resource);
+  for (const candidate of authServerMetadataUrls(issuer)) {
+    const body = await getJson(candidate);
+    if (body !== null) return toServer(body, issuer, scopes);
+  }
+  throw refused(
+    `${resource.hostname} needs authorization, but publishes no OAuth metadata Metro can use.`,
+  );
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth-routes.ts

@@ -0,0 +1,158 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { bodyField, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import {
+  beginOAuth,
+  completeOAuth,
+  prepareOAuth,
+  takePending,
+  type PendingAuth,
+} from './oauth.js';
+import { connectorClient } from './config.js';
+import { parseConnectorUrl } from './verify.js';
+import type { OAuthAuth } from './verify.js';
+import type { Connector, PendingConnectorInput } from './store.js';
+
+const asText = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return '';
+  }
+}
+
+export interface OAuthRouteDeps {
+  createPendingConnector: (input: PendingConnectorInput) => Promise<Connector>;
+  reconnectConnector: (id: string, auth: OAuthAuth) => Promise<Connector>;
+  getConnector: (id: string) => Promise<Connector>;
+}
+
+export async function startOAuth(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  body: unknown,
+  payload: (row: Connector) => Record<string, unknown>,
+): Promise<void> {
+  const url = parseConnectorUrl(bodyField(body, 'url'));
+  const returnTo = asText(bodyField(body, 'returnTo'));
+  const clientId = bodyField(body, 'clientId');
+  const clientSecret = bodyField(body, 'clientSecret');
+  const prepared = await prepareOAuth({
+    url,
+    client: connectorClient(clientId, clientSecret),
+    returnTo,
+  });
+  const row = await deps.createPendingConnector({
+    name: bodyField(body, 'name'),
+    url: bodyField(body, 'url'),
+    clientId,
+    clientSecret,
+  });
+  const authorize = beginOAuth(prepared, {
+    name: row.name,
+    url,
+    returnTo,
+    connectorId: row.id,
+  });
+  log.info(
+    { id: row.id, host: url.hostname },
+    'connector-api: stored unconnected, sending the user to sign in',
+  );
+  sendJson(req, res, 201, { ...payload(row), authorizeUrl: authorize });
+}
+
+export async function handleConnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  id: string,
+): Promise<void> {
+  const row = await deps.getConnector(id);
+  const url = parseConnectorUrl(row.url);
+  const body = await readJsonBody(req);
+  const returnTo = asText(bodyField(body, 'returnTo'));
+  const prepared = await prepareOAuth({ url, client: row.client, returnTo });
+  const authorize = beginOAuth(prepared, {
+    name: row.name,
+    url,
+    returnTo,
+    connectorId: row.id,
+  });
+  log.info(
+    { id: row.id, host: url.hostname },
+    'connector-api: sending the user back to sign in',
+  );
+  sendJson(req, res, 202, { status: 'oauth', authorizeUrl: authorize });
+}
+
+function landing(entry: PendingAuth, id?: string): string {
+  const target = id ?? entry.connectorId;
+  return target === undefined ? '#/connectors' : `#/connector/${target}`;
+}
+
+function backTo(entry: PendingAuth, error?: string, id?: string): string {
+  const suffix =
+    error === undefined
+      ? ''
+      : `?connector_error=${encodeURIComponent(error)}`;
+  return `${entry.returnTo}${suffix}${landing(entry, id)}`;
+}
+
+function redirect(res: ServerResponse, location: string): void {
+  res.writeHead(302, { location, 'cache-control': 'no-store' }).end();
+}
+
+async function saveOAuth(
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  auth: OAuthAuth,
+): Promise<Connector> {
+  return deps.reconnectConnector(entry.connectorId, auth);
+}
+
+async function settleCallback(
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  code: string,
+): Promise<void> {
+  try {
+    const auth = await completeOAuth(entry, code);
+    const saved = await saveOAuth(deps, entry, auth);
+    log.info(
+      { id: saved.id, name: saved.name, host: hostOf(saved.url) },
+      'connector-api: oauth sign-in completed',
+    );
+    redirect(res, backTo(entry, undefined, saved.id));
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'connector-api: oauth sign-in failed');
+    redirect(res, backTo(entry, errMsg(err)));
+  }
+}
+
+export function handleCallback(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+): void {
+  const query = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+  const entry = takePending(query.get('state') ?? '');
+  if (entry === undefined) {
+    sendJson(req, res, 400, { error: 'that sign-in has expired — start it again' });
+    return;
+  }
+  const denied = query.get('error');
+  const code = query.get('code') ?? '';
+  if (denied !== null || code === '') {
+    redirect(res, backTo(entry, denied ?? 'no authorization code came back'));
+    return;
+  }
+  settleCallback(res, deps, entry, code).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'connector-api: oauth callback failed');
+    if (!res.headersSent) redirect(res, backTo(entry, 'sign-in failed'));
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth.ts

@@ -0,0 +1,166 @@
+import { publicBaseOrDefault } from '../files/attach-serve.js';
+import {
+  refused,
+  type OAuthAuth,
+  type OAuthTokens,
+} from './verify.js';
+import { validateReturnTo } from '@metro-labs/http/return-to';
+import {
+  authorizeUrl,
+  exchangeCode,
+  newVerifier,
+  refreshTokens,
+  registerClient,
+  type OAuthClient,
+} from './oauth-client.js';
+import { discoverOAuth, type OAuthServer } from './oauth-discovery.js';
+import { ticketStore } from '@metro-labs/core/tickets';
+
+export interface PendingAuth {
+  name: string;
+  url: string;
+  resource: string;
+  returnTo: string;
+  verifier: string;
+  server: OAuthServer;
+  client: OAuthClient;
+  connectorId: string;
+}
+
+const pending = ticketStore<PendingAuth>(10 * 60_000, 100);
+
+export const startPending = (entry: PendingAuth, now = Date.now()): string => pending.mint(entry, now).ticket;
+
+export const takePending = (state: string, now = Date.now()): PendingAuth | undefined => pending.take(state, now);
+
+export const pendingCount = (): number => pending.size();
+
+const REFRESH_SKEW_MS = 300_000;
+
+const CALLBACK_PATH = '/api/connectors/callback';
+
+const callbackUri = (): string =>
+  `${publicBaseOrDefault()}${CALLBACK_PATH}`;
+
+const resourceOf = (url: URL): string => url.toString();
+
+export interface PrepareInput {
+  url: URL;
+  client: OAuthClient | null;
+  returnTo: string;
+}
+
+export interface PreparedOAuth {
+  server: OAuthServer;
+  client: OAuthClient;
+  redirectUri: string;
+}
+
+export async function prepareOAuth(input: PrepareInput): Promise<PreparedOAuth> {
+  if (!validateReturnTo(input.returnTo))
+    throw refused('that return address is not one Metro will send you back to');
+  const server = await discoverOAuth(input.url);
+  const redirectUri = callbackUri();
+  const client = input.client ?? (await registerClient(server, redirectUri));
+  return { server, client, redirectUri };
+}
+
+export interface BeginInput {
+  connectorId: string;
+  name: string;
+  url: URL;
+  returnTo: string;
+}
+
+export function beginOAuth(prepared: PreparedOAuth, input: BeginInput): string {
+  const { server, client, redirectUri } = prepared;
+  const verifier = newVerifier();
+  const resource = resourceOf(input.url);
+  const state = startPending({
+    name: input.name,
+    url: input.url.toString(),
+    resource,
+    returnTo: input.returnTo,
+    verifier,
+    server,
+    client,
+    connectorId: input.connectorId,
+  });
+  return authorizeUrl({
+    server,
+    client,
+    redirectUri,
+    state,
+    verifier,
+    resource,
+  });
+}
+
+function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
+  return {
+    kind: 'oauth',
+    issuer: pendingAuth.server.issuer,
+    tokenEndpoint: pendingAuth.server.tokenEndpoint,
+    clientId: pendingAuth.client.clientId,
+    ...(pendingAuth.client.clientSecret === undefined
+      ? {}
+      : { clientSecret: pendingAuth.client.clientSecret }),
+    ...(pendingAuth.server.scopes.length === 0
+      ? {}
+      : { scope: pendingAuth.server.scopes.join(' ') }),
+    ...tokens,
+  };
+}
+
+export async function completeOAuth(
+  entry: PendingAuth,
+  code: string,
+): Promise<OAuthAuth> {
+  const tokens = await exchangeCode(entry.server, entry.client, {
+    code,
+    redirectUri: callbackUri(),
+    verifier: entry.verifier,
+    resource: entry.resource,
+  });
+  return authOf(entry, tokens);
+}
+
+export function oauthExpired(auth: OAuthAuth, now = Date.now()): boolean {
+  return auth.expiresAt !== undefined && auth.expiresAt - REFRESH_SKEW_MS <= now;
+}
+
+export async function refreshOAuth(
+  auth: OAuthAuth,
+  resource: string,
+): Promise<OAuthAuth> {
+  if (auth.refreshToken === undefined)
+    throw refused('that connector needs signing in again');
+  const server = {
+    issuer: auth.issuer,
+    authorizationEndpoint: '',
+    tokenEndpoint: auth.tokenEndpoint,
+    registrationEndpoint: null,
+    supportsS256: true,
+    scopes: [],
+  };
+  const client = {
+    clientId: auth.clientId,
+    ...(auth.clientSecret === undefined
+      ? {}
+      : { clientSecret: auth.clientSecret }),
+  };
+  const tokens = await refreshTokens(
+    server,
+    client,
+    auth.refreshToken,
+    resource,
+    auth.scope,
+  );
+  return {
+    ...auth,
+    ...tokens,
+    ...(tokens.refreshToken === undefined
+      ? { refreshToken: auth.refreshToken }
+      : {}),
+  };
+}