@synap-core/sdk 1.3.0 → 1.4.0

package/README.md

@@ -119,7 +119,7 @@ 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)
+## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0, 1.4.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
@@ -142,20 +142,33 @@ export const synap = createPodAppAuth({
     { permission: "entity.post.create", reason: "Save drafts to your pod" },
   ],
   secret: process.env.SYNAP_APP_SESSION_SECRET!, // ≥ 32 chars, never NEXT_PUBLIC_
+  cloudUrl: process.env.SYNAP_CLOUD_URL, // optional (1.4): https://api.synap.live offers "Continue with Synap Cloud"
 });
 
 // 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/connect/route.ts               export const POST = synap.handlers.connect;    // form { pod, next?, space?, prompt? }
 // 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? }
+// app/api/synap/cloud/route.ts (1.4)           export const POST = synap.handlers.cloudConnect; // form { next?, space?, prompt? }
+//                                              export const GET = synap.handlers.cloudReturn;
 ```
 
 ```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
+// out.lapsed (with none, 1.4): { podUrl } when this browser WAS connected and the connection lapsed
 // send out.setCookies on the response; forward out.cookieHeader (when set) as the request's Cookie
 
+// Next 16 strips its router headers before proxy code runs, so skip prefetches in the MATCHER
+// (it still sees them; matcher values must be literals):
+export const config = {
+  matcher: [{
+    source: "/((?!_next/static|_next/image|api/synap/|\\.well-known/|.*\\.\\w+$).*)",
+    missing: [{ type: "header", key: "next-router-prefetch" }, { type: "header", key: "purpose", value: "prefetch" }],
+  }],
+};
+
 // 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!);
@@ -168,8 +181,7 @@ if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupp
   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`.
+  connect page.
 - **Failures** redirect with `?error=<ConnectErrorCode>`: `denied`,
   `expired_transaction`, `mismatch`, `misconfigured`, `rate_limited`,
   `pod_unreachable`, … (`parseConnectErrorCode` reads it back). `connect` and
@@ -184,19 +196,81 @@ if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupp
   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.
+  The pod's reuse grace (PB3b) answers a spent token presented again within
+  30 s with the same pair the first use got; its `expires_in` may be under an
+  hour, and the SDK reads it as sent.
 - **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`.
+  `revokeConnection`, `buildClientMetadata`, `seal`/`unseal`,
+  `startCloudConnect`, `acceptCloudReturn`.
+
+### 1.4.0 (additive)
+
+- **Re-consent**: the connect form's `prompt=consent` (or `startConnect({ prompt: "consent" })`)
+  goes to the pod's consent screen even when this browser is already connected to
+  that pod (to widen or narrow access). It is a normal sign-in: fresh PKCE verifier
+  and state, `iss` checked; a denied or forged answer leaves the live connection as it is.
+- **Synap Cloud** (wave C1): with `cloudUrl` set, `synap.cloudConnectAvailable` is
+  true and `cloudConnectAvailable({ cloudUrl })` too. POST `handlers.cloudConnect`
+  sends the browser to `<cp>/connect/pod?client_id=<client id>&state=<nonce>`, the
+  state sealed in an HttpOnly cookie of that browser (10 minutes). The CP returns to
+  the CIMD `initiate_login_uri?iss=<pod>&state=<nonce>` (your connect page):
+  `acceptLaunch(url).cloudState` is set, so forward the request's query to GET
+  `handlers.cloudReturn`, which checks the state against the cookie (constant time,
+  single use) BEFORE the pod is used, then runs the same sign-in as a typed address.
+  `acceptLaunch` itself never verifies anything; a return without a matching state
+  starts no sign-in (`mismatch`, `expired_transaction`). A cancel on the chooser
+  (`?state=…&error=access_denied`, no `iss`) also carries `cloudState`: forwarded the
+  same way, it lands on the connect page with `?error=denied` once the state matched.
+  Security notes: after the state matches, the named pod goes through the same
+  discovery as a typed address (metadata, `issuer` equality, CIMD, `iss`, S256)
+  before the browser is sent anywhere. The cloud cookie is single-use and cleared on
+  every outcome (success, cancel, mismatch). Accepted trade-off: a third-party page
+  that sends a visitor's browser to a forged return can cancel that visitor's Cloud
+  sign-in in progress (they click again); nothing leaks and nothing is bound, the
+  same nuisance any OAuth `state` check allows.
+
+  ```typescript
+  // app/connect/page.tsx (server component)
+  const launch = acceptLaunch(url, origin);
+  if (launch.cloudState) redirect(`${synap.paths.cloud}${new URL(url).search}`);
+  ```
+- **`connection.manageUrl` / `connection.appId`**: the pod's page for this app
+  connection (pod-admin `/apps/<appId>`), read from the token response's
+  `synap_app: { id, manageUrl }` (https only). Absent when the pod does not send it:
+  hide the link, never build one.
+- **`client.listPendingProposals({ workspaceId?, limit?, offset? })`**: "Waiting for
+  review: N" (`data.total`, plus summary rows with `reviewUrl`) from the pod's seamed
+  `GET /proposals` door. Ask for `proposal.read` in `requests`: without it the answer
+  is `forbidden` and nothing is sent (the pod would answer an empty list). It counts
+  the person's pending proposals in those spaces, from any agent.
+- **`spaces(connection)` / `client.spaces()`**: the grant by space
+  (`{ workspaceId, workspaceName, permissions }`), each permission once.
+- **Expired vs never connected**: each sign-in and refresh also sets a marker cookie
+  (`__Host-synap_seen`, 400 days) holding the pod's URL and nothing else.
+  `synap.readLapsed(cookieHeader)` and `RefreshOutcome.lapsed` say "this browser was
+  connected to <pod>" once the sealed session is gone; a disconnect clears it.
+- **`isPrefetchOrAsset(request)`** is exported, and its limit documented: inside
+  Next 16's proxy a router prefetch is invisible (see the matcher above).
+- Not added: `ensureTemplate` on the pod-app client. A pod-app key's grant is pinned
+  to the approved spaces, so creating a space is refused by the pod's grant check
+  every time; ask for templates with `templates` (CIMD `synap_templates`) instead:
+  the pod's consent offers to create the space.
 
 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`):
+refresh with the 30 s reuse grace, `/revoke`, Hub REST doors: `GET /entities`
+answers an array as the pod does, `GET /proposals` lists what proposed writes
+filed; `synap_app` is `MOCK_APP` unless `app: null`; `writeMode`, `failures`, `refresh: false`, `entities`,
+`refreshGraceSec`), and `createMockCloud()` for the Synap Cloud pod chooser:
 
 ```typescript
 const pod = createMockAuthServer();
-const synap = createPodAppAuth({ ...config, fetch: pod.fetch });
+const cloud = createMockCloud();
+const synap = createPodAppAuth({ ...config, fetch: pod.fetch, cloudUrl: cloud.url });
 // POST connect → Location → pod.authorize(location) → GET callback with that URL
+// POST cloud → Location → cloud.choose(location, { pod: pod.issuer, metadata: synap.metadata }) → forward to GET cloud
 ```
 
 ## Mock pod: `@synap-core/sdk/testing`

package/dist/{client-CVUT1Mcf.d.cts → client-C5sF20f1.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 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 };
+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 };

package/dist/{client-CVUT1Mcf.d.ts → client-C5sF20f1.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 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 };
+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 };