@synap-core/sdk 1.2.0 → 1.3.0

package/README.md

@@ -119,6 +119,86 @@ SDK refuses out-of-bounds `offset`/`limit`/`sort` locally, without a request),
 pass `ifNoneMatch` from a browser: the doors allow no cross-origin request header
 but `Content-Type`, so the preflight fails (browsers revalidate on their own).
 
+## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0)
+
+An app that reads and writes a person's OWN pod connects as an OAuth 2.1 public
+client of that pod: its `client_id` is the https URL of its client metadata
+document (CIMD), PKCE S256, every answer checked for the pod's `iss`. The pod
+token stays on the app's server, sealed (AES-GCM) in an HttpOnly cookie; the
+browser never sees it. Framework-free and Web-standard (`Request` → `Response`,
+WebCrypto): Next route handlers and `proxy.ts`, Hono, Remix, edge runtimes.
+**Server-only**: it throws when loaded in a browser, and a browser bundle
+resolves it to a stub that throws.
+
+```typescript
+// lib/synap/pod-app/auth.ts (server-only)
+import { createPodAppAuth } from "@synap-core/sdk/connect";
+
+export const synap = createPodAppAuth({
+  appUrl: process.env.SITE_URL!, // https://studio.example.com
+  clientName: "Studio",
+  requests: [
+    { permission: "entity.post.read", reason: "Show your posts" },
+    { permission: "entity.post.create", reason: "Save drafts to your pod" },
+  ],
+  secret: process.env.SYNAP_APP_SESSION_SECRET!, // ≥ 32 chars, never NEXT_PUBLIC_
+});
+
+// app/.well-known/synap-client.json/route.ts  export const GET = synap.handlers.clientMetadata;
+// app/api/synap/connect/route.ts               export const POST = synap.handlers.connect;    // form { pod, next?, space? }
+// app/api/synap/callback/route.ts              export const GET = synap.handlers.callback;
+// app/api/synap/disconnect/route.ts            export const POST = synap.handlers.disconnect; // form { next? }
+```
+
+```typescript
+// proxy.ts: refresh before render (server components cannot set cookies)
+const out = await synap.refreshIfNeeded(request);
+// out.status: none | skipped | fresh | refreshed | kept | expired | revoked | unavailable
+// send out.setCookies on the response; forward out.cookieHeader (when set) as the request's Cookie
+
+// a server component / action (no Request there: pass the Cookie header)
+const connection = await synap.readConnection((await headers()).get("cookie"));
+const pod = synap.client(connection!);
+const res = await pod.post("/entities", { profileSlug: "post", title: "Hello" });
+if (res.ok && res.status === "proposed") showPending(res.reviewUrl); // success: queued for review, never retry
+if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupported | rate_limited (retryAfterSec) | pod_unreachable | …
+```
+
+- **Discovery**: `discoverPod("pod.example.com")` fetches the pod's RFC 8414
+  metadata and requires `issuer` equal to the address, CIMD, `iss` on answers and
+  S256 (`not_a_pod`, `pod_unsupported`, `pod_unreachable`). A browser launch
+  (`?iss=…&target_link_uri=…`) is read with `acceptLaunch` and only pre-fills the
+  connect page. Synap Cloud discovery is not available yet:
+  `cloudConnectAvailable()` is `false`.
+- **Failures** redirect with `?error=<ConnectErrorCode>`: `denied`,
+  `expired_transaction`, `mismatch`, `misconfigured`, `rate_limited`,
+  `pod_unreachable`, … (`parseConnectErrorCode` reads it back). `connect` and
+  `disconnect` are POST and same-origin only.
+- **Refresh** (rotating, single-use, 30 days from issue) is feature-detected: a
+  pod that issues no `refresh_token` gives a connection that ends with its
+  1-hour access token. `refreshIfNeeded` rotates only inside the last 5
+  minutes, is single-flight per connection in the process, and persists the
+  rotated connection BEFORE returning it. The pod revokes the whole connection
+  when a spent refresh token is presented again, so for 2 minutes a request
+  still carrying the spent token (a parallel request, a second tab) gets the
+  rotation's result instead of reaching the pod. Across server instances only
+  a shared server-side `ConnectionStore` rules that replay out. A concurrent
+  loser (refused softly by the pod) keeps the still-valid access token.
+- **Your own store**: implement `ConnectionStore` (`read`, `write`, `clear`,
+  returning Set-Cookie values) and pass it as `store`.
+- Lower level: `startConnect`, `handleCallback`, `refreshConnection`,
+  `revokeConnection`, `buildClientMetadata`, `seal`/`unseal`.
+
+Test without a pod: `createMockAuthServer()` from `@synap-core/sdk/testing`
+(metadata, `authorize()` as the consent screen, `/token` with PKCE, rotating
+refresh, `/revoke`, Hub REST doors; `writeMode`, `failures`, `refresh: false`):
+
+```typescript
+const pod = createMockAuthServer();
+const synap = createPodAppAuth({ ...config, fetch: pod.fetch });
+// POST connect → Location → pod.authorize(location) → GET callback with that URL
+```
+
 ## Mock pod: `@synap-core/sdk/testing`
 
 A fake `fetch` that answers the public doors (forms, shares, sites) from fixtures,

package/dist/chunk-J7XHAAFJ.js

@@ -0,0 +1,79 @@
+// src/connect/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8(text) {
+  return encoder.encode(text);
+}
+function fromUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function base64url(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64url(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
+  let binary;
+  try {
+    binary = atob(padded);
+  } catch {
+    return null;
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function randomBytes(length) {
+  const out = new Uint8Array(length);
+  crypto.getRandomValues(out);
+  return out;
+}
+function randomToken() {
+  return base64url(randomBytes(32));
+}
+async function pkceChallenge(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", utf8(verifier));
+  return base64url(new Uint8Array(digest));
+}
+function constantTimeEqual(a, b) {
+  const x = utf8(a);
+  const y = utf8(b);
+  let diff = x.length ^ y.length;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+  return diff === 0;
+}
+function parseCookies(header) {
+  const out = /* @__PURE__ */ new Map();
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (!name || out.has(name)) continue;
+    let value = part.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+    out.set(name, value);
+  }
+  return out;
+}
+function serializeCookie(name, value, attrs) {
+  const parts = [`${name}=${value}`, "Path=/", "HttpOnly", "SameSite=Lax", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];
+  if (attrs.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+export {
+  utf8,
+  fromUtf8,
+  base64url,
+  fromBase64url,
+  randomBytes,
+  randomToken,
+  pkceChallenge,
+  constantTimeEqual,
+  parseCookies,
+  serializeCookie
+};
+//# sourceMappingURL=chunk-J7XHAAFJ.js.map

package/dist/chunk-J7XHAAFJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/encoding.ts"],"sourcesContent":["/**\n * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code\n * runs on Node 18+, edge runtimes and workers. No Node import.\n */\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\n/** `Uint8Array<ArrayBuffer>`: what WebCrypto's `BufferSource` takes under TS 5.7+ lib types. */\nexport type Bytes = Uint8Array<ArrayBuffer>;\n\nexport function utf8(text: string): Bytes {\n  return encoder.encode(text);\n}\n\nexport function fromUtf8(bytes: Uint8Array): string {\n  return decoder.decode(bytes);\n}\n\nexport function base64url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Null when `text` is not base64url. */\nexport function fromBase64url(text: string): Bytes | null {\n  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;\n  const padded = text.replace(/-/g, \"+\").replace(/_/g, \"/\") + \"===\".slice((text.length + 3) % 4);\n  let binary: string;\n  try {\n    binary = atob(padded);\n  } catch {\n    return null;\n  }\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\nexport function randomBytes(length: number): Bytes {\n  const out = new Uint8Array(length);\n  crypto.getRandomValues(out);\n  return out;\n}\n\n/** 32 random bytes, base64url (43 chars): a state value or a PKCE verifier. */\nexport function randomToken(): string {\n  return base64url(randomBytes(32));\n}\n\n/** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */\nexport async function pkceChallenge(verifier: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", utf8(verifier));\n  return base64url(new Uint8Array(digest));\n}\n\n/** Compare two strings without an early exit on the first differing byte. */\nexport function constantTimeEqual(a: string, b: string): boolean {\n  const x = utf8(a);\n  const y = utf8(b);\n  let diff = x.length ^ y.length;\n  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);\n  return diff === 0;\n}\n\n/** The request's cookies by name (the first value wins, as browsers order the most specific first). */\nexport function parseCookies(header: string | null): Map<string, string> {\n  const out = new Map<string, string>();\n  if (!header) return out;\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq < 0) continue;\n    const name = part.slice(0, eq).trim();\n    if (!name || out.has(name)) continue;\n    let value = part.slice(eq + 1).trim();\n    if (value.startsWith('\"') && value.endsWith('\"')) value = value.slice(1, -1);\n    out.set(name, value);\n  }\n  return out;\n}\n\nexport interface CookieAttributes {\n  maxAgeSec: number;\n  secure: boolean;\n}\n\n/** `HttpOnly; SameSite=Lax; Path=/` always; `Secure` on https. Never a `Domain`. */\nexport function serializeCookie(name: string, value: string, attrs: CookieAttributes): string {\n  const parts = [`${name}=${value}`, \"Path=/\", \"HttpOnly\", \"SameSite=Lax\", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];\n  if (attrs.secure) parts.push(\"Secure\");\n  return parts.join(\"; \");\n}\n"],"mappings":";AAKA,IAAM,UAAU,IAAI,YAAY;AAChC,IAAM,UAAU,IAAI,YAAY;AAKzB,SAAS,KAAK,MAAqB;AACxC,SAAO,QAAQ,OAAO,IAAI;AAC5B;AAEO,SAAS,SAAS,OAA2B;AAClD,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAEO,SAAS,UAAU,OAA2B;AACnD,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,IAAK,WAAU,OAAO,aAAa,MAAM,CAAC,CAAC;AAC7E,SAAO,KAAK,MAAM,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AAC/E;AAGO,SAAS,cAAc,MAA4B;AACxD,MAAI,CAAC,mBAAmB,KAAK,IAAI,EAAG,QAAO;AAC3C,QAAM,SAAS,KAAK,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG,IAAI,MAAM,OAAO,KAAK,SAAS,KAAK,CAAC;AAC7F,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,MAAM,IAAI,WAAW,OAAO,MAAM;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,KAAI,CAAC,IAAI,OAAO,WAAW,CAAC;AACpE,SAAO;AACT;AAEO,SAAS,YAAY,QAAuB;AACjD,QAAM,MAAM,IAAI,WAAW,MAAM;AACjC,SAAO,gBAAgB,GAAG;AAC1B,SAAO;AACT;AAGO,SAAS,cAAsB;AACpC,SAAO,UAAU,YAAY,EAAE,CAAC;AAClC;AAGA,eAAsB,cAAc,UAAmC;AACrE,QAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK,QAAQ,CAAC;AACnE,SAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC;AAGO,SAAS,kBAAkB,GAAW,GAAoB;AAC/D,QAAM,IAAI,KAAK,CAAC;AAChB,QAAM,IAAI,KAAK,CAAC;AAChB,MAAI,OAAO,EAAE,SAAS,EAAE;AACxB,WAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAK,UAAS,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,KAAK;AACtF,SAAO,SAAS;AAClB;AAGO,SAAS,aAAa,QAA4C;AACvE,QAAM,MAAM,oBAAI,IAAoB;AACpC,MAAI,CAAC,OAAQ,QAAO;AACpB,aAAW,QAAQ,OAAO,MAAM,GAAG,GAAG;AACpC,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,KAAK,EAAG;AACZ,UAAM,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACpC,QAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,EAAG;AAC5B,QAAI,QAAQ,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK;AACpC,QAAI,MAAM,WAAW,GAAG,KAAK,MAAM,SAAS,GAAG,EAAG,SAAQ,MAAM,MAAM,GAAG,EAAE;AAC3E,QAAI,IAAI,MAAM,KAAK;AAAA,EACrB;AACA,SAAO;AACT;AAQO,SAAS,gBAAgB,MAAc,OAAe,OAAiC;AAC5F,QAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,UAAU,YAAY,gBAAgB,WAAW,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE;AAC9H,MAAI,MAAM,OAAQ,OAAM,KAAK,QAAQ;AACrC,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}

package/dist/{client-C5sF20f1.d.cts → client-CVUT1Mcf.d.cts}

@@ -250,4 +250,4 @@ interface PublicClient {
 }
 declare function createPublicClient(opts: PublicClientOptions): PublicClient;
 
-export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicRecordSummary as b, type PublicValue as c, type PublicCollectionPage as d, type PublicRecord as e, type PublicResult as f, type PublicShare as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };
+export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicShare as a, type PublicRecord as b, type PublicReadError as c, type PublicRecordSummary as d, type PublicValue as e, type PublicCollectionPage as f, type PublicResult as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };

package/dist/{client-C5sF20f1.d.ts → client-CVUT1Mcf.d.ts}

@@ -250,4 +250,4 @@ interface PublicClient {
 }
 declare function createPublicClient(opts: PublicClientOptions): PublicClient;
 
-export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicRecordSummary as b, type PublicValue as c, type PublicCollectionPage as d, type PublicRecord as e, type PublicResult as f, type PublicShare as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };
+export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicShare as a, type PublicRecord as b, type PublicReadError as c, type PublicRecordSummary as d, type PublicValue as e, type PublicCollectionPage as f, type PublicResult as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };

package/dist/connect.browser.cjs

@@ -0,0 +1,22 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/connect/browser.ts
+var browser_exports = {};
+module.exports = __toCommonJS(browser_exports);
+throw new Error(
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. Import it from route handlers, proxy.ts or server code, never from a client component."
+);
+//# sourceMappingURL=connect.browser.cjs.map

package/dist/connect.browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/browser.ts"],"sourcesContent":["/**\n * What a BROWSER bundle gets for `@synap-core/sdk/connect` (the `browser`\n * export condition): no exports, and a throw on load. See ./guard.ts.\n */\nthrow new Error(\n  \"@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. \" +\n    \"Import it from route handlers, proxy.ts or server code, never from a client component.\",\n);\n\nexport {};\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;AAIA,MAAM,IAAI;AAAA,EACR;AAEF;","names":[]}

package/dist/connect.browser.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/connect.browser.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/connect.browser.js

@@ -0,0 +1,5 @@
+// src/connect/browser.ts
+throw new Error(
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. Import it from route handlers, proxy.ts or server code, never from a client component."
+);
+//# sourceMappingURL=connect.browser.js.map

package/dist/connect.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/browser.ts"],"sourcesContent":["/**\n * What a BROWSER bundle gets for `@synap-core/sdk/connect` (the `browser`\n * export condition): no exports, and a throw on load. See ./guard.ts.\n */\nthrow new Error(\n  \"@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. \" +\n    \"Import it from route handlers, proxy.ts or server code, never from a client component.\",\n);\n\nexport {};\n"],"mappings":";AAIA,MAAM,IAAI;AAAA,EACR;AAEF;","names":[]}