@modfolio/connect-sdk

Modfolio Connect SSO/OIDC SDK for ecosystem apps. v8.3.0.

Install

bun add @modfolio/connect-sdk

Published to public npm — no token or .npmrc needed. (A legacy GitHub Packages mirror still exists; using it requires @modfolio:registry=https://npm.pkg.github.com plus a GitHub Packages token, but new apps should use public npm.)

Quick Start (SvelteKit)

// src/lib/server/auth.ts
import { createSvelteKitAuth } from "@modfolio/connect-sdk/sveltekit";

export const auth = createSvelteKitAuth({
  clientId: "your-app-name",
});

// src/hooks.server.ts
import { auth } from "$lib/server/auth";
export const handle = auth.handle;

// src/routes/auth/login/+server.ts
export const GET = auth.loginHandler;

// src/routes/auth/callback/+server.ts
export const GET = auth.callbackHandler;

// src/routes/auth/logout/+server.ts
export const GET = auth.logoutHandler;

Adapters

| Framework | Import | Factory | |-----------|--------|---------| | SvelteKit 5 | @modfolio/connect-sdk/sveltekit | createSvelteKitAuth() | | Astro | @modfolio/connect-sdk/astro | createAstroAuth() | | SolidStart | @modfolio/connect-sdk/solidstart | createSolidStartAuth() | | Nuxt 3 | @modfolio/connect-sdk/nuxt | createNuxtAuth() | | Next.js | @modfolio/connect-sdk/nextjs | createNextAuth() (App + Pages Router) | | Qwik | @modfolio/connect-sdk/qwik | createQwikAuth() | | Hono (CF Workers) | @modfolio/connect-sdk/hono | createHonoAuth() |

Utility export paths: ./ssf (CAEP receiver) · ./dpop · ./fedcm · ./quick-login (browser helper) · ./agent (MCP) · ./management · ./management-client.

Quick Login (8.3.0)

For apps on modfolio.io / *.modfolio.io the Connect IdP session cookie (Domain=.modfolio.io) is visible server-side, so the SvelteKit and Astro adapters sign returning visitors in automatically — an anonymous top-level GET page load carrying that cookie 302s straight to /sso/authorize?prompt=none (no /auth/login hop). Silent failure lands back on the page anonymous; a short-TTL mc_ql marker suppresses retry loops, and logout sets a 1h mc_lo marker so "I logged out" sticks until the next interactive login.

createSvelteKitAuth({
  clientId: "your-app-name",
  quickLogin: {
    autoLogin: "same-site-only", // default; true = any origin, false = off
    backgroundRefresh: true,     // default: refresh BEFORE expiry (≤500ms cap)
    optimistic: false,           // opt-in: display-only locals.userHint
  },
});

• backgroundRefresh removes the 15-minute idle cliff: when ≤5min of token lifetime remains, the adapter refreshes best-effort (hard 500ms cap) while still serving the request from the current valid token. The post-expiry blocking refresh remains as last resort.
• optimistic exposes locals.userHint ({ id, email, name, avatar? }) from an expired-but-signature-valid session while a refresh soft-fails — display-only; NEVER authorize with it. locals.user stays null until a real refresh succeeds.
• External domains (gistcore.com, …) never see the IdP cookie; use the ./quick-login browser helper (initQuickLogin({ probe: true })) once the /sso/session-probe endpoint ships — it is a no-op by default.

Path protection

protectedPaths is a prefix allowlist — "/" matches every path. publicPaths (SvelteKit / Astro / Next.js / Nuxt) is evaluated before protectedPaths, and /api/webhooks/ + /.well-known/ are built-in always-public so self-authenticated webhook receivers can never be shadowed behind a login redirect:

createSvelteKitAuth({
  clientId: "your-app-name",
  protectedPaths: ["/"],          // boot-time warning reminds you about "/"
  publicPaths: ["/api/audio/"],   // own-auth/public API prefixes
});

Back-Channel Logout — mounting it may not be enough

backchannelLogoutHandler (10.0.0) makes a global logout take effect immediately instead of at token expiry. Mount it, then register the URL with Connect.

⚠ Three adapters answer 403 before the handler ever runs. OIDC mandates Content-Type: application/x-www-form-urlencoded, which is exactly the shape meta-frameworks treat as a cross-site form post:

| Adapter | Gate on by default | How to open it | |---|---|---| | SvelteKit | yes — csrf.checkOrigin | kit: { csrf: { trustedOrigins: ['https://login.modfolio.io'] } } | | Astro | yes — security.checkOrigin (server output) | no allowlist: security: { checkOrigin: false } app-wide, or host the URI off-Astro | | Qwik | yes — origin vs ORIGIN env | no allowlist: createQwikCity({ checkOrigin: false }), or host the URI off-Qwik | | Hono | no — csrf() is opt-in | if enabled, allow the Connect origin | | Next.js | no — Route Handlers are not Server Actions | — | | Nuxt | no | (needs 10.2.0 on Cloudflare) | | SolidStart | no | — |

⚠ SvelteKit: that key does not have to live in svelte.config.js. SvelteKit 2's Vite plugin takes the same KitConfig inline — sveltekit(config?: KitConfig & …) — so an app configured entirely from vite.config.ts already has a home for it:

// vite.config.ts — for an app with no svelte.config.js
sveltekit({ csrf: { trustedOrigins: ["https://login.modfolio.io"] } });

Reported by a first-time adopter (visualize, 2026-08-05) who has no svelte.config.js at all: following the row above verbatim would have created one, leaving the app's configuration split across two files that both look authoritative. Put it wherever your KitConfig already is.

Connect sends Origin: <its login_url> (default https://login.modfolio.io) as of 2026-08-04. Before that it sent none — and SvelteKit's check short-circuits on a missing Origin, so no trustedOrigins entry could have worked, however it was written.

Verify with a probe rather than assuming. POST form-encoded garbage at your mounted URL:

curl -si -X POST https://yourapp.example/auth/backchannel-logout \
  -H 'content-type: application/x-www-form-urlencoded' --data 'logout_token=x'

400 is the success signal — the handler ran and rejected an invalid token. 403 means the framework is still in front of it.

Token verification

verifyToken validates signature, issuer and (since 8.3.0) aud === clientId — Connect issues app tokens with aud = client_id, so tokens minted for another client are rejected. Escape hatch: verifyAudience: false.

Management API (PAT)

Programmatic app management with a Personal Access Token (mfp_…, issued at account.modfolio.io/developers/tokens). Two equivalent surfaces:

// Typed client — request/response types generated from the OpenAPI spec
import { createManagementClient } from "@modfolio/connect-sdk/management-client";

const connect = createManagementClient({ token: process.env.MODFOLIO_PAT! });
const { client_id } = await connect.createClient({
  name: "My App",
  redirect_uris: ["https://myapp.com/auth/callback"],
});

// Function helpers — same wire calls, handwritten types
import { registerApp, whoami } from "@modfolio/connect-sdk/management";

Methods: whoami · listClients · getClient · createClient · renameClient · deleteClient · addRedirectUri · removeRedirectUri · getScopes. Non-2xx responses throw ManagementError (.status, .code).

The types in src/generated/ are rendered from docs/openapi.json by bun run docs:openapi (repo root) and kept byte-fresh by the openapi:drift quality gate — never edit them by hand.

Defaults

| Config | Default | Purpose | |--------|---------|---------| | connectUrl | https://login.modfolio.io | OIDC API | | loginUrl | https://login.modfolio.io | Login UI redirect | | issuer | https://connect.modfolio.io | JWT issuer verification | | sessionCookie | mc_session | Session cookie name | | scope | openid profile email | OIDC scopes |

Flow

1. App /auth/login redirects to https://login.modfolio.io/{clientId} with PKCE S256
2. User authenticates on hosted login page
3. Login redirects to app /auth/callback with code + state
4. SDK exchanges code at POST /sso/token
5. SDK verifies JWT (issuer: https://connect.modfolio.io) and sets session cookie

Full Guide

See docs/sdk-integration-guide.md for:

• All 5 framework examples with complete route setup
• ConnectUser type reference
• Utility functions (MFA, org, tenant, ReBAC, webhooks)
• Local dev port assignments (22 apps)
• CF Pages build configuration

Upgrade notes:

• docs/sdk-v4-upgrade.md covers the v3 to v4 tenant-aware changes.