@synap-core/sdk 1.2.0 → 1.4.0

package/src/connect/client.ts

@@ -0,0 +1,299 @@
+/**
+ * A server-side Hub REST client for one PodConnection: `<pod>/api/hub/*` with
+ * the connection's Bearer token. Results, not throws: `{ ok: true, … }` or
+ * `{ ok: false, error }` with a typed `code`.
+ *
+ *  - `expired`: the access token is past its expiry here; nothing was sent
+ *    (refresh in `proxy.ts` / a route handler, or connect again);
+ *  - `unauthorized`: the pod refused the token (revoked, or expired there);
+ *  - `forbidden`: not granted; `door_unsupported`: a door a space-scoped app
+ *    token can never use (403 GRANT_DOOR_UNSUPPORTED, spec 17 §5);
+ *  - `rate_limited` with `retryAfterSec`; `pod_unreachable` (network, 502-504).
+ *
+ * Writes are governed: `proposed` is SUCCESS (queued for the person's review,
+ * never retry it), with `reviewUrl` on the pod.
+ *
+ * The token goes to the pod's own origin only: paths are pod-relative, no
+ * redirect is followed.
+ */
+import { retryAfterSeconds } from "./errors";
+import type { PodConnection, PodGrant, PodSpace } from "./types";
+
+export type PodErrorCode =
+  | "expired"
+  | "unauthorized"
+  | "forbidden"
+  | "door_unsupported"
+  | "not_found"
+  | "invalid"
+  | "conflict"
+  | "rate_limited"
+  | "pod_unreachable"
+  | "server";
+
+export interface PodError {
+  code: PodErrorCode;
+  /** The HTTP status, or null when nothing was answered. */
+  status: number | null;
+  retryAfterSec?: number;
+  /** The pod's own error text, for logs only. */
+  detail?: string;
+}
+
+export type PodResult<T> = { ok: true; data: T } | { ok: false; error: PodError };
+
+export type PodWriteResult<T> =
+  | { ok: true; status: "applied"; data: T }
+  | { ok: true; status: "proposed"; proposalId: string | null; reviewUrl: string; data: T }
+  | { ok: false; error: PodError };
+
+export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+
+/** One pending proposal, the pod's summary row (`GET /proposals?view=basic`). */
+export interface PendingProposal {
+  id: string;
+  proposalType: string;
+  targetType: string;
+  targetId: string | null;
+  workspaceId: string | null;
+  /** ISO 8601, as the pod sent it. */
+  createdAt: string;
+  /** The agent that filed it (this app's agent, or another one), when known. */
+  agentUserId: string | null;
+  sessionId: string | null;
+  summary?: string;
+  /** Where the person reviews it: the pod's deep link. */
+  reviewUrl: string;
+}
+
+export interface PendingProposals {
+  /** Every pending proposal the connection can see, not only this page (the pod COUNTs it). */
+  total: number;
+  proposals: PendingProposal[];
+  hasMore: boolean;
+}
+
+export interface ListPendingProposalsOptions {
+  /** One granted space only. */
+  workspaceId?: string;
+  /** 1-200, default 20. */
+  limit?: number;
+  offset?: number;
+}
+
+export interface PodClientOptions {
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+export interface PodClient {
+  podUrl: string;
+  user: PodConnection["user"];
+  grant: PodGrant[];
+  /** Whether the connection was granted `permission` (in `workspaceId` when given). */
+  can(permission: string, workspaceId?: string): boolean;
+  /** The granted spaces, each with its permissions (`spaces(connection)`). */
+  spaces(): PodSpace[];
+  /**
+   * "Waiting for review: N". The person's pending proposals in the spaces this
+   * connection may read proposals in (any agent's, not only this app's), from
+   * the pod's seamed `GET /proposals` door. Needs the `proposal.read`
+   * permission (ask for it in `requests`): without it the pod would answer an
+   * empty list, so this answers `forbidden` instead, without a request.
+   */
+  listPendingProposals(opts?: ListPendingProposalsOptions): Promise<PodResult<PendingProposals>>;
+  get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
+  post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+  patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+  put<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+  delete<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+}
+
+/** Whether `connection` was granted `permission` (in `workspaceId` when given). Exact match: grants carry no wildcard. */
+export function can(connection: Pick<PodConnection, "grant">, permission: string, workspaceId?: string): boolean {
+  return connection.grant.some((g) => g.permission === permission && (workspaceId === undefined || g.workspaceId === workspaceId));
+}
+
+/**
+ * The grant by space, in the grant's order, each permission once. The pod
+ * sends one row per permission per space; a space switcher wants one per space.
+ */
+export function spaces(connection: Pick<PodConnection, "grant">): PodSpace[] {
+  const bySpace = new Map<string, PodSpace>();
+  for (const g of connection.grant) {
+    const space = bySpace.get(g.workspaceId) ?? { workspaceId: g.workspaceId, workspaceName: g.workspaceName, permissions: [] };
+    if (!space.workspaceName && g.workspaceName) space.workspaceName = g.workspaceName;
+    if (!space.permissions.includes(g.permission)) space.permissions.push(g.permission);
+    bySpace.set(g.workspaceId, space);
+  }
+  return [...bySpace.values()];
+}
+
+const SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
+
+function hubUrl(podUrl: string, path: string, query?: Record<string, QueryValue>): URL {
+  if (!SAFE_PATH.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) {
+    throw new TypeError(`Not a Hub API path: ${path}`);
+  }
+  const url = new URL(`${podUrl}/api/hub${path}`);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value === undefined || value === null) continue;
+    for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(v));
+  }
+  return url;
+}
+
+function errorFor(status: number, body: unknown, retryAfter: string | null, now: number): PodError {
+  const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : undefined;
+  const base = { status, ...(detail !== undefined ? { detail } : {}) };
+  if (status === 401) return { code: "unauthorized", ...base };
+  if (status === 403) return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden", ...base };
+  if (status === 404) return { code: "not_found", ...base };
+  if (status === 409) return { code: "conflict", ...base };
+  if (status === 400 || status === 422) return { code: "invalid", ...base };
+  if (status === 429) {
+    const retryAfterSec = retryAfterSeconds(retryAfter, now);
+    return { code: "rate_limited", ...base, ...(retryAfterSec !== undefined ? { retryAfterSec } : {}) };
+  }
+  if (status === 502 || status === 503 || status === 504) return { code: "pod_unreachable", ...base };
+  return { code: "server", ...base };
+}
+
+/**
+ * Where to review a proposal: the pod's answer, resolved against the pod and
+ * kept only on the pod's own origin; else the pod's deep link `/open/<id>`.
+ */
+export function reviewUrlFor(podUrl: string, reviewUrl: unknown, proposalId: string | null): string {
+  if (typeof reviewUrl === "string" && reviewUrl) {
+    try {
+      const url = new URL(reviewUrl, `${podUrl}/`);
+      if (url.origin === new URL(podUrl).origin) return url.href;
+    } catch {
+      // fall through to the deep link
+    }
+  }
+  return proposalId ? `${podUrl}/open/${encodeURIComponent(proposalId)}` : podUrl;
+}
+
+export function createPodClient(connection: PodConnection, opts: PodClientOptions = {}): PodClient {
+  const now = opts.now ?? Date.now;
+  const doFetch = () => opts.fetch ?? fetch;
+
+  async function request(method: string, path: string, body: unknown, query?: Record<string, QueryValue>): Promise<PodResult<unknown>> {
+    const url = hubUrl(connection.podUrl, path, query);
+    if (connection.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
+    const headers: Record<string, string> = { Accept: "application/json", Authorization: `Bearer ${connection.accessToken}` };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    let res: Response;
+    try {
+      res = await doFetch()(url.href, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "manual",
+      });
+    } catch {
+      return { ok: false, error: { code: "pod_unreachable", status: null } };
+    }
+    let data: unknown = null;
+    const text = await res.text().catch(() => "");
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = null;
+      }
+    }
+    if (res.status >= 200 && res.status < 300) return { ok: true, data };
+    return { ok: false, error: errorFor(res.status, data, res.headers.get("retry-after"), now()) };
+  }
+
+  async function write<T>(method: string, path: string, body: unknown): Promise<PodWriteResult<T>> {
+    const result = await request(method, path, body);
+    if (!result.ok) return result;
+    const obj = result.data && typeof result.data === "object" ? (result.data as Record<string, unknown>) : {};
+    const proposalId = typeof obj.proposalId === "string" && obj.proposalId ? obj.proposalId : null;
+    if (obj.status === "proposed" || (obj.status === "pending" && proposalId)) {
+      return {
+        ok: true,
+        status: "proposed",
+        proposalId,
+        reviewUrl: reviewUrlFor(connection.podUrl, obj.reviewUrl, proposalId),
+        data: result.data as T,
+      };
+    }
+    return { ok: true, status: "applied", data: result.data as T };
+  }
+
+  async function listPendingProposals(opts: ListPendingProposalsOptions = {}): Promise<PodResult<PendingProposals>> {
+    if (!can(connection, "proposal.read", opts.workspaceId)) {
+      return {
+        ok: false,
+        error: { code: "forbidden", status: null, detail: "The connection was not granted proposal.read in that space" },
+      };
+    }
+    const limit = Math.min(Math.max(Math.floor(opts.limit ?? 20), 1), 200);
+    const offset = Math.max(Math.floor(opts.offset ?? 0), 0);
+    const result = await request("GET", "/proposals", undefined, {
+      status: "pending",
+      view: "basic",
+      limit,
+      offset,
+      workspaceId: opts.workspaceId,
+    });
+    if (!result.ok) return result;
+    const obj = result.data && typeof result.data === "object" ? (result.data as Record<string, unknown>) : {};
+    if (!Array.isArray(obj.proposals) || typeof obj.total !== "number") {
+      return { ok: false, error: { code: "server", status: 200, detail: "The pod's /proposals answer has no proposals or total" } };
+    }
+    const str = (v: unknown): string | null => (typeof v === "string" && v ? v : null);
+    const proposals: PendingProposal[] = [];
+    for (const row of obj.proposals as unknown[]) {
+      if (!row || typeof row !== "object") continue;
+      const r = row as Record<string, unknown>;
+      const id = str(r.id);
+      if (!id) continue;
+      proposals.push({
+        id,
+        proposalType: str(r.proposalType) ?? "",
+        targetType: str(r.targetType) ?? "",
+        targetId: str(r.targetId),
+        workspaceId: str(r.workspaceId),
+        createdAt: str(r.createdAt) ?? "",
+        agentUserId: str(r.agentUserId),
+        sessionId: str(r.sessionId),
+        ...(str(r.summary) ? { summary: str(r.summary)! } : {}),
+        reviewUrl: reviewUrlFor(connection.podUrl, null, id),
+      });
+    }
+    return {
+      ok: true,
+      data: { total: obj.total, proposals, hasMore: obj.hasMore === true || offset + proposals.length < obj.total },
+    };
+  }
+
+  return {
+    podUrl: connection.podUrl,
+    user: connection.user,
+    grant: connection.grant,
+    can: (permission, workspaceId) => can(connection, permission, workspaceId),
+    spaces: () => spaces(connection),
+    listPendingProposals,
+    get<T>(path: string, query?: Record<string, QueryValue>) {
+      return request("GET", path, undefined, query) as Promise<PodResult<T>>;
+    },
+    post<T>(path: string, body?: unknown) {
+      return write<T>("POST", path, body);
+    },
+    patch<T>(path: string, body?: unknown) {
+      return write<T>("PATCH", path, body);
+    },
+    put<T>(path: string, body?: unknown) {
+      return write<T>("PUT", path, body);
+    },
+    delete<T>(path: string, body?: unknown) {
+      return write<T>("DELETE", path, body);
+    },
+  };
+}

package/src/connect/cloud.ts

@@ -0,0 +1,206 @@
+/**
+ * Connecting through Synap Cloud (wave C1, doc 18 §1.1): the person picks
+ * their pod on the Control Plane instead of typing its address.
+ *
+ *   app  POST <cloud handler>            → 303 <cp>/connect/pod?client_id=<CIMD url>&state=<nonce>
+ *   CP   the person signs in, picks a pod → 302 <initiate_login_uri>?iss=<pod issuer>&state=<nonce>
+ *   app  GET  <cloud handler>?iss&state  → state checked against this browser's sealed
+ *                                          cookie → the SAME sign-in as a typed address
+ *                                          (discovery, fresh PKCE + state, `iss` on the answer)
+ *
+ * The CP never sees a code or a token, and takes the return URL from the
+ * app's client metadata, never from the query. `state` is what makes the
+ * return trustworthy: it is drawn here, kept sealed in an HttpOnly cookie of
+ * this browser, and compared in constant time, so an `iss` link that another
+ * site sends a visitor to (login CSRF into an attacker's pod) is refused. A
+ * return without a matching `state` never starts a sign-in.
+ *
+ * The CP's answer only names a pod. The pod itself is then validated exactly
+ * like a typed address (`discoverPod`), and its answer like any other.
+ */
+import { canonicalPodUrl } from "./discovery";
+import { constantTimeEqual, randomToken } from "./encoding";
+import { ConnectError, fromOAuthError } from "./errors";
+import { seal, unseal, type AppSecret } from "./seal";
+
+/** How long a Synap Cloud sign-in may take, from the click to the pod chooser's return. */
+export const CLOUD_TRANSACTION_TTL_MS = 10 * 60 * 1000;
+
+/** The state the CP accepts (`^[A-Za-z0-9._~-]{16,256}$`); ours is 43 base64url characters. */
+const STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** A sealed `CloudTransaction`: opaque, safe to put in an HttpOnly cookie. */
+export type SealedCloudTransaction = string & { readonly __sealedCloudTransaction: true };
+
+/** What a started Synap Cloud sign-in remembers (sealed; never sent to the CP). */
+export interface CloudTransaction {
+  v: 1;
+  state: string;
+  clientId: string;
+  /** The CP base it was sent to. */
+  cloudUrl: string;
+  next: string | null;
+  spaceHint: string | null;
+  prompt: "consent" | null;
+  createdAt: number;
+}
+
+export interface CloudConnectConfig {
+  /** The Control Plane's base URL, e.g. https://api.synap.live. Unset = no Synap Cloud option. */
+  cloudUrl?: string | null;
+  /** Accept a CP on http://localhost (development). */
+  allowInsecureLoopback?: boolean;
+}
+
+/** The CP base (no trailing slash), or a ConnectError (`misconfigured`). */
+export function cloudBaseUrl(cloudUrl: string, opts: { allowInsecureLoopback?: boolean } = {}): string {
+  let url: URL;
+  try {
+    url = new URL(cloudUrl.trim());
+  } catch {
+    throw new ConnectError("misconfigured", "cloudUrl is not a URL");
+  }
+  const loopback = LOOPBACK_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback && opts.allowInsecureLoopback)) {
+    throw new ConnectError("misconfigured", "cloudUrl must be https (http only on localhost in development)");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new ConnectError("misconfigured", "cloudUrl has no credentials, query or fragment");
+  }
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+
+/** Whether "Continue with Synap Cloud" can be offered: a valid Control Plane URL is configured. */
+export function cloudConnectAvailable(config?: CloudConnectConfig | null): boolean {
+  if (!config?.cloudUrl) return false;
+  try {
+    cloudBaseUrl(config.cloudUrl, config);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface StartCloudConnectOptions extends CloudConnectConfig {
+  /** The app's client_id (its CIMD URL): the CP reads `initiate_login_uri` from it. */
+  clientId: string;
+  /** SERVER-ONLY app secret that seals the transaction. */
+  secret?: AppSecret;
+  /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
+  next?: string | null;
+  /** A space to preselect on the pod's consent. */
+  spaceHint?: string | null;
+  /** Show the pod's consent again even if this browser is already connected to the pod the person picks. */
+  prompt?: "consent" | null;
+  /** @deprecated Ignored: the SDK always draws its own 32-byte state. */
+  state?: string;
+  now?: () => number;
+}
+
+export interface StartedCloudConnect {
+  /** Redirect the browser here (303): the CP's pod chooser. */
+  url: string;
+  /** Store in an HttpOnly cookie until the CP returns. */
+  transaction: SealedCloudTransaction;
+  /** ms since epoch. */
+  expiresAt: number;
+}
+
+/**
+ * Start a Synap Cloud sign-in. Throws `cp_unavailable` at once when no CP URL
+ * is configured (as 1.3 always did), `misconfigured` without a secret.
+ */
+export function startCloudConnect(opts: StartCloudConnectOptions): Promise<StartedCloudConnect> {
+  if (!cloudConnectAvailable(opts)) {
+    throw new ConnectError("cp_unavailable", "cp: not configured — pass cloudUrl (the Control Plane URL) to offer Synap Cloud");
+  }
+  if (!opts.secret) throw new ConnectError("misconfigured", "startCloudConnect needs the app secret to seal its state");
+  const base = cloudBaseUrl(opts.cloudUrl!, opts);
+  const secret = opts.secret;
+  return (async () => {
+    const now = (opts.now ?? Date.now)();
+    const state = randomToken();
+    const url = new URL(`${base}/connect/pod`);
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("state", state);
+    const tx: CloudTransaction = {
+      v: 1,
+      state,
+      clientId: opts.clientId,
+      cloudUrl: base,
+      next: opts.next ?? null,
+      spaceHint: opts.spaceHint ?? null,
+      prompt: opts.prompt === "consent" ? "consent" : null,
+      createdAt: now,
+    };
+    const expiresAt = now + CLOUD_TRANSACTION_TTL_MS;
+    const transaction = (await seal(tx, { secret, purpose: "synap-connect/cloud", expiresAt })) as SealedCloudTransaction;
+    return { url: url.href, transaction, expiresAt };
+  })();
+}
+
+export interface AcceptCloudReturnOptions {
+  /** The URL the CP sent the browser back to (`?iss=…&state=…`). */
+  url: string | URL;
+  transaction: string | null | undefined;
+  clientId: string;
+  secret: AppSecret;
+  allowInsecureLoopback?: boolean;
+  now?: () => number;
+}
+
+export interface CloudReturn {
+  /** The pod the person picked (canonical issuer), still to be discovered and validated. */
+  pod: string;
+  next: string | null;
+  spaceHint: string | null;
+  prompt: "consent" | null;
+}
+
+/**
+ * Check the CP's return against the sealed transaction of THIS browser.
+ * Throws `expired_transaction` (none, foreign, tampered or older than 10
+ * minutes), `mismatch` (the state is not this browser's, or no pod is named),
+ * `denied` (the person cancelled on the chooser: `error=access_denied`, no
+ * `iss`; nothing is started), `invalid_pod_address`.
+ * `state` is compared BEFORE anything else in the query is used.
+ */
+export async function acceptCloudReturn(opts: AcceptCloudReturnOptions): Promise<CloudReturn> {
+  if (!opts.transaction) throw new ConnectError("expired_transaction", "No Synap Cloud sign-in in progress in this browser");
+  const opened = await unseal<CloudTransaction>(opts.transaction, {
+    secret: opts.secret,
+    purpose: "synap-connect/cloud",
+    now: (opts.now ?? Date.now)(),
+  });
+  if (!opened.ok) {
+    throw new ConnectError(
+      "expired_transaction",
+      opened.reason === "expired" ? "The Synap Cloud sign-in is older than 10 minutes" : "The Synap Cloud cookie is not one this app sealed",
+    );
+  }
+  const tx = opened.value;
+  if (!tx || tx.v !== 1 || typeof tx.state !== "string") {
+    throw new ConnectError("expired_transaction", "The Synap Cloud cookie is not one this app sealed");
+  }
+  if (tx.clientId !== opts.clientId) {
+    throw new ConnectError("misconfigured", "The Synap Cloud sign-in was started for another client_id");
+  }
+  const params = new URL(opts.url).searchParams;
+  const state = params.get("state");
+  if (state === null || !STATE_RE.test(state) || !constantTimeEqual(state, tx.state)) {
+    throw new ConnectError("mismatch", "The Synap Cloud answer does not belong to the sign-in this browser started");
+  }
+  const error = params.get("error");
+  if (error !== null) {
+    throw new ConnectError(fromOAuthError(error, "authorize"), `Synap Cloud answered ${error}`, { oauthError: error });
+  }
+  const iss = params.get("iss");
+  if (!iss) throw new ConnectError("mismatch", "The Synap Cloud answer names no pod");
+  return {
+    pod: canonicalPodUrl(iss, opts),
+    next: tx.next,
+    spaceHint: tx.spaceHint,
+    prompt: tx.prompt === "consent" ? "consent" : null,
+  };
+}