@synap-core/sdk 1.1.0 → 1.3.0

package/src/connect/store.ts

@@ -0,0 +1,151 @@
+/**
+ * Where a PodConnection lives between requests. The default keeps it in the
+ * browser as a SEALED cookie (AES-GCM under the app secret, HttpOnly, Secure
+ * on https, SameSite=Lax, Path=/, `__Host-` prefix on https): the browser holds
+ * ciphertext it cannot read or forge, the pod token never reaches JS.
+ *
+ * Bring your own (a database, a KV) by implementing `ConnectionStore`; it
+ * answers with the Set-Cookie values to send (e.g. its own session id).
+ */
+import { parseCookies, serializeCookie } from "./encoding";
+import { ConnectError } from "./errors";
+import { seal, unseal, type AppSecret } from "./seal";
+import type { PodConnection, PodGrant } from "./types";
+
+export interface ConnectionStore {
+  /** The request's connection, or null (absent, tampered, foreign, expired). */
+  read(request: Request): Promise<PodConnection | null>;
+  /** Persist; returns the Set-Cookie header values to send. */
+  write(connection: PodConnection, request: Request): Promise<string[]>;
+  /** Forget; returns the Set-Cookie header values to send. */
+  clear(request: Request): Promise<string[]>;
+}
+
+export interface CookieNames {
+  session: string;
+  transaction: string;
+}
+
+/** `__Host-` names on https (Secure, Path=/, no Domain: bound to this exact host). */
+export function cookieNames(secure: boolean): CookieNames {
+  return secure
+    ? { session: "__Host-synap_session", transaction: "__Host-synap_tx" }
+    : { session: "synap_session", transaction: "synap_tx" };
+}
+
+/** Browsers cap a cookie near 4096 bytes; a big grant spans several. */
+const CHUNK_SIZE = 3800;
+const MAX_CHUNKS = 4;
+
+function chunkName(name: string, i: number): string {
+  return i === 0 ? name : `${name}.${i}`;
+}
+
+/** The sealed form: the grant grouped per space (it repeats the space otherwise). */
+interface StoredConnection extends Omit<PodConnection, "grant"> {
+  g: Array<[workspaceId: string, workspaceName: string, permissions: string[]]>;
+}
+
+function pack(c: PodConnection): StoredConnection {
+  const bySpace = new Map<string, [string, string, string[]]>();
+  for (const g of c.grant) {
+    const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
+    row[2].push(g.permission);
+    bySpace.set(g.workspaceId, row);
+  }
+  const { grant: _grant, ...rest } = c;
+  return { ...rest, g: [...bySpace.values()] };
+}
+
+function unpack(s: StoredConnection): PodConnection | null {
+  if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
+  const { g, ...rest } = s;
+  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions]) =>
+    permissions.map((permission) => ({ permission, workspaceId, workspaceName })),
+  );
+  return { ...rest, grant };
+}
+
+/** When the stored value stops being useful. */
+export function connectionExpiresAt(c: PodConnection): number {
+  return c.refreshToken && c.refreshExpiresAt !== undefined ? Math.max(c.refreshExpiresAt, c.accessExpiresAt) : c.accessExpiresAt;
+}
+
+export interface SealedCookieStoreOptions {
+  secret: AppSecret;
+  /** True on https (the default when the app URL is https). */
+  secure: boolean;
+  name?: string;
+  now?: () => number;
+}
+
+export function createSealedCookieStore(opts: SealedCookieStoreOptions): ConnectionStore {
+  const name = opts.name ?? cookieNames(opts.secure).session;
+  const now = opts.now ?? Date.now;
+
+  const presentChunks = (request: Request) => {
+    const cookies = parseCookies(request.headers.get("cookie"));
+    const names: string[] = [];
+    for (let i = 0; i < MAX_CHUNKS; i++) if (cookies.has(chunkName(name, i))) names.push(chunkName(name, i));
+    return { cookies, names };
+  };
+
+  return {
+    async read(request) {
+      const { cookies } = presentChunks(request);
+      let sealed = "";
+      for (let i = 0; i < MAX_CHUNKS; i++) {
+        const part = cookies.get(chunkName(name, i));
+        if (part === undefined) break;
+        sealed += part;
+      }
+      if (!sealed) return null;
+      const opened = await unseal<StoredConnection>(sealed, { secret: opts.secret, purpose: "synap-connect/session", now: now() });
+      return opened.ok ? unpack(opened.value) : null;
+    },
+
+    async write(connection, request) {
+      const expiresAt = connectionExpiresAt(connection);
+      const sealed = await seal(pack(connection), { secret: opts.secret, purpose: "synap-connect/session", expiresAt });
+      const parts: string[] = [];
+      for (let i = 0; i < sealed.length; i += CHUNK_SIZE) parts.push(sealed.slice(i, i + CHUNK_SIZE));
+      if (parts.length > MAX_CHUNKS) {
+        throw new ConnectError(
+          "misconfigured",
+          "The connection is too large for a cookie (a very wide grant); pass a server-side ConnectionStore",
+        );
+      }
+      const maxAgeSec = (expiresAt - now()) / 1000;
+      const out = parts.map((value, i) => serializeCookie(chunkName(name, i), value, { maxAgeSec, secure: opts.secure }));
+      // Drop chunks a previous, larger value left behind.
+      for (const stale of presentChunks(request).names.slice(parts.length)) {
+        out.push(serializeCookie(stale, "", { maxAgeSec: 0, secure: opts.secure }));
+      }
+      return out;
+    },
+
+    async clear(request) {
+      const { names } = presentChunks(request);
+      return (names.length > 0 ? names : [name]).map((n) => serializeCookie(n, "", { maxAgeSec: 0, secure: opts.secure }));
+    },
+  };
+}
+
+/**
+ * Apply Set-Cookie values to a request's Cookie header, so code that runs
+ * later IN THE SAME REQUEST (a server component after `proxy.ts`) reads the
+ * refreshed value. A `Max-Age=0` removes the cookie.
+ */
+export function applySetCookies(cookieHeader: string | null, setCookies: readonly string[]): string {
+  const cookies = parseCookies(cookieHeader);
+  for (const sc of setCookies) {
+    const [pair, ...attrs] = sc.split(";");
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    const name = pair.slice(0, eq).trim();
+    const removed = attrs.some((a) => /^\s*max-age\s*=\s*0\s*$/i.test(a));
+    if (removed) cookies.delete(name);
+    else cookies.set(name, pair.slice(eq + 1).trim());
+  }
+  return [...cookies].map(([k, v]) => `${k}=${v}`).join("; ");
+}

package/src/connect/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Wire and session shapes of pod-app sign-in.
+ *
+ * DRIFT RISK: hand-written from the pod's OAuth AS (synap-backend
+ * `routers/oauth/routes.ts` /token for a CIMD client, `protocol.ts`
+ * `buildAuthorizationServerMetadata`, spec 17 §6.6). The contract fixture
+ * `src/__tests__/connect.contract.test.ts` copies the token response; when the
+ * backend changes, update both.
+ */
+
+/** One permission the app asks for, with the sentence the consent screen shows. */
+export interface AppRequest {
+  /** Grant grammar, e.g. `entity.post.read`, `document.update`. No `*`. */
+  permission: string;
+  /** Why the app needs it (at most 200 characters). */
+  reason: string;
+}
+
+/** What the person approved: one row per permission per space. */
+export interface PodGrant {
+  permission: string;
+  workspaceId: string;
+  workspaceName: string;
+}
+
+export interface PodUser {
+  id: string;
+  name: string;
+}
+
+/** A pod's authorization server, as `discoverPod` validated it. */
+export interface PodIssuer {
+  /** The canonical issuer, which is also the pod's base URL. */
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  revocationEndpoint: string | null;
+  /** The AS advertises `grant_types_supported: [..., "refresh_token"]`. */
+  refreshSupported: boolean;
+}
+
+/**
+ * A live connection of this app to one person's pod. Server-only: it holds the
+ * bearer token. Serialisable, so a custom store can keep it anywhere.
+ */
+export interface PodConnection {
+  /** The pod's canonical issuer = its base URL (no trailing slash). */
+  podUrl: string;
+  /** The app's client_id (its CIMD URL) the tokens were issued to. */
+  clientId: string;
+  tokenEndpoint: string;
+  revocationEndpoint: string | null;
+  accessToken: string;
+  /** ms since epoch. */
+  accessExpiresAt: number;
+  /** Absent when the pod issued none (then the connection ends at `accessExpiresAt`). */
+  refreshToken?: string;
+  /** ms since epoch; the refresh token's idle life, renewed by each rotation. */
+  refreshExpiresAt?: number;
+  /** The approved permissions (the token response's `scope`). */
+  scope: string[];
+  grant: PodGrant[];
+  user: PodUser;
+  /** ms since epoch. */
+  connectedAt: number;
+}
+
+/** The CIMD document an app serves at its client_id URL (spec 17 §6.1). */
+export interface ClientMetadataDocument {
+  client_id: string;
+  client_name: string;
+  client_uri: string;
+  redirect_uris: string[];
+  grant_types: string[];
+  response_types: string[];
+  token_endpoint_auth_method: "none";
+  initiate_login_uri: string;
+  synap_requests: AppRequest[];
+  synap_templates?: string[];
+}

package/src/index.ts

@@ -1,2 +1,15 @@
 export { createSynapClient } from "./client";
 export type { SynapClient, SynapClientOptions, AppRouter } from "./client";
+export {
+  ensureTemplate,
+  ensuredWorkspaceId,
+  parseEnsureTemplateResult,
+} from "./templates";
+export type {
+  EnsureTemplateClient,
+  EnsureTemplateInput,
+  EnsureTemplateMissingTemplate,
+  EnsureTemplateOptions,
+  EnsureTemplateResult,
+  EnsureTemplateStatus,
+} from "./templates";