@sovereignfs/sdk 1.25.0 → 2.0.1

package/dist/index.js

@@ -1,652 +1,1363 @@
 import {
-  __export
-} from "./chunk-MLKGABMK.js";
+  ConfigurationError,
+  CoreApiError,
+  CoreUnavailableError,
+  NotAuthenticatedError,
+  NotSupportedError,
+  SessionEndedError,
+  SignInError,
+  SovereignError
+} from "./chunk-NYL4LLXF.js";
 
-// src/auth.ts
-var auth_exports = {};
-__export(auth_exports, {
-  changePassword: () => changePassword,
-  getSession: () => getSession,
-  hasCapability: () => hasCapability,
-  listSessions: () => listSessions,
-  requireSession: () => requireSession,
-  revokeSession: () => revokeSession,
-  signOut: () => signOut
-});
-import { headers } from "next/headers";
+// ../api-client/src/generated/operations.ts
+var operations = {
+  dismissAllNotifications: {
+    method: "POST",
+    path: "/api/v1/notifications/dismiss-all",
+    scopes: ["notifications"],
+    safeToRepeat: false
+  },
+  dismissNotification: {
+    method: "POST",
+    path: "/api/v1/notifications/{id}/dismiss",
+    scopes: ["notifications"],
+    safeToRepeat: false
+  },
+  findDirectoryUserByEmail: {
+    method: "GET",
+    path: "/api/v1/directory/users/by-email",
+    scopes: ["directory"],
+    safeToRepeat: true
+  },
+  getInstanceBranding: {
+    method: "GET",
+    path: "/.well-known/sovereign-instance",
+    scopes: void 0,
+    safeToRepeat: true
+  },
+  listNotifications: {
+    method: "GET",
+    path: "/api/v1/notifications",
+    scopes: ["notifications"],
+    safeToRepeat: true
+  },
+  logActivity: {
+    method: "POST",
+    path: "/api/v1/activity",
+    scopes: ["activity:write"],
+    safeToRepeat: false
+  },
+  markAllNotificationsRead: {
+    method: "POST",
+    path: "/api/v1/notifications/read-all",
+    scopes: ["notifications"],
+    safeToRepeat: false
+  },
+  markNotificationRead: {
+    method: "POST",
+    path: "/api/v1/notifications/{id}/read",
+    scopes: ["notifications"],
+    safeToRepeat: false
+  },
+  resolveDirectoryUsers: {
+    method: "POST",
+    path: "/api/v1/directory/users/resolve",
+    scopes: ["directory"],
+    safeToRepeat: true
+  },
+  searchDirectoryUsers: {
+    method: "GET",
+    path: "/api/v1/directory/users",
+    scopes: ["directory"],
+    safeToRepeat: true
+  },
+  sendEmail: {
+    method: "POST",
+    path: "/api/v1/email",
+    scopes: ["email:send"],
+    safeToRepeat: false
+  },
+  sendNotification: {
+    method: "POST",
+    path: "/api/v1/notifications",
+    scopes: ["notifications:send"],
+    safeToRepeat: false
+  }
+};
 
-// src/errors.ts
-var NotImplementedError = class extends Error {
-  constructor(message) {
+// ../api-client/src/client.ts
+var CoreApiError2 = class extends Error {
+  constructor(status, code, message, retryAfter) {
     super(message);
-    this.name = "NotImplementedError";
+    this.status = status;
+    this.code = code;
+    this.retryAfter = retryAfter;
   }
+  status;
+  code;
+  retryAfter;
+  name = "CoreApiError";
 };
-var NotAuthenticatedError = class extends Error {
-  constructor() {
-    super("No authenticated session. The caller must be within an authenticated request.");
-    this.name = "NotAuthenticatedError";
+function createCoreClient(options) {
+  const base = new URL(options.baseUrl);
+  const client2 = {};
+  for (const name of Object.keys(operations)) {
+    client2[name] = (given = {}) => call(options, base, name, given);
   }
-};
-var ConsentRequiredError = class extends Error {
-  constructor(message = "User consent is required to access this plugin data.") {
-    super(message);
-    this.name = "ConsentRequiredError";
+  return client2;
+}
+async function call(options, base, name, given) {
+  const operation = operations[name];
+  let path = operation.path;
+  for (const [key, value] of Object.entries(given.params ?? {})) {
+    path = path.replace(`{${key}}`, encodeURIComponent(value));
   }
-};
-var EntitlementRequiredError = class extends Error {
-  constructor(message = "An active entitlement is required to access this feature.") {
-    super(message);
-    this.name = "EntitlementRequiredError";
+  const url2 = new URL(path, base);
+  for (const [key, value] of Object.entries(given.query ?? {})) {
+    if (value !== void 0) url2.searchParams.set(key, String(value));
   }
-};
-
-// src/sessions.ts
-function markCurrentSessions(sessions, currentToken) {
-  return sessions.map((s) => ({
-    token: s.token,
-    current: s.token === currentToken,
-    userAgent: s.userAgent ?? null,
-    ipAddress: s.ipAddress ?? null,
-    createdAt: s.createdAt,
-    updatedAt: s.updatedAt,
-    expiresAt: s.expiresAt
-  })).sort((a, b) => {
-    if (a.current !== b.current) return a.current ? -1 : 1;
-    return a.createdAt < b.createdAt ? 1 : -1;
+  const headers = { accept: "application/json" };
+  if (operation.scopes !== void 0) {
+    const token = typeof options.token === "function" ? await options.token() : options.token ?? void 0;
+    if (!token) throw new Error(`${name} needs an access token: give the client a \`token\`.`);
+    headers.authorization = `Bearer ${token}`;
+  }
+  let body;
+  if (given.body !== void 0) {
+    headers["content-type"] = "application/json";
+    body = JSON.stringify(given.body);
+  }
+  const reply = await (options.fetch ?? fetch)(url2, {
+    method: operation.method,
+    headers,
+    ...body === void 0 ? {} : { body }
   });
+  if (reply.ok) return reply.json();
+  throw await failure(reply);
+}
+async function failure(reply) {
+  let code = "unknown";
+  let message = `Core answered ${reply.status}.`;
+  try {
+    const body = await reply.json();
+    if (typeof body.error === "string") code = body.error;
+    if (typeof body.message === "string") message = body.message;
+  } catch {
+  }
+  const retry = Number(reply.headers.get("retry-after"));
+  return new CoreApiError2(
+    reply.status,
+    code,
+    message,
+    reply.status === 429 && Number.isFinite(retry) && retry > 0 ? retry : void 0
+  );
 }
 
 // src/auth.ts
-var DEFAULT_TENANT_ID = "default";
-var AUTH_URL = process.env.SOVEREIGN_AUTH_URL ?? `http://localhost:${process.env.AUTH_PORT ?? "3001"}`;
-async function getSession() {
-  const h = await headers();
-  const id = h.get("x-sovereign-user-id");
-  if (!id) return null;
-  const role = h.get("x-sovereign-user-role") ?? "platform:user";
-  const capsRaw = h.get("x-sovereign-user-capabilities");
-  const capabilities = capsRaw ? JSON.parse(capsRaw) : [];
-  return {
-    user: {
-      id,
-      // v1 is single-tenant, so every session belongs to the default tenant.
-      // Multi-tenant deployments will source this from the verified session.
-      tenantId: DEFAULT_TENANT_ID,
-      email: h.get("x-sovereign-user-email") ?? "",
-      name: h.get("x-sovereign-user-name") ?? null,
-      image: h.get("x-sovereign-user-image") ?? null,
-      role,
-      capabilities
-    },
-    expiresAt: Number(h.get("x-sovereign-session-expires-at") ?? 0)
-  };
+import * as client from "openid-client";
+import {
+  createRemoteJWKSet,
+  customFetch as joseFetch,
+  jwtVerify,
+  errors as joseErrors
+} from "jose";
+
+// src/session.ts
+function hasRole(session, role) {
+  return session.roles.includes(role);
 }
-function hasCapability(session, capability) {
-  return session?.user.capabilities.includes(capability) ?? false;
+var cookieName = (kind, secure) => `${secure ? "__Host-" : ""}sv_${kind}`;
+function setCookie(name, value, options) {
+  return `${name}=${value}; Path=/; HttpOnly; SameSite=Lax${options.secure ? "; Secure" : ""}; Max-Age=${Math.max(0, Math.floor(options.maxAgeSeconds))}`;
 }
-async function requireSession() {
-  const session = await getSession();
-  if (!session) throw new NotAuthenticatedError();
-  return session;
+var clearCookie = (name, secure) => setCookie(name, "", { secure, maxAgeSeconds: 0 });
+function readCookies(header) {
+  const found = {};
+  for (const part of (header ?? "").split(";")) {
+    const at = part.indexOf("=");
+    if (at < 1) continue;
+    const name = part.slice(0, at).trim();
+    if (!(name in found)) found[name] = part.slice(at + 1).trim();
+  }
+  return found;
 }
-async function authFetch(path, method, body) {
-  const cookie = (await headers()).get("cookie") ?? "";
-  return fetch(`${AUTH_URL}${path}`, {
-    method,
-    headers: {
-      cookie,
-      origin: AUTH_URL,
-      ...body === void 0 ? {} : { "Content-Type": "application/json" }
-    },
-    body: body === void 0 ? void 0 : JSON.stringify(body)
-  });
+function newId() {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-async function authError(res, action) {
-  const body = await res.text().catch(() => "");
-  const detail = body ? ` \u2014 ${body}` : "";
-  return new Error(`${action} (${String(res.status)})${detail}`);
+function localPath(value) {
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.includes("\\"))
+    return "/";
+  if (/[\u0000-\u001f]/.test(value)) return "/";
+  return value;
 }
-async function changePassword(input) {
-  const res = await authFetch("/api/auth/change-password", "POST", {
-    currentPassword: input.currentPassword,
-    newPassword: input.newPassword,
-    revokeOtherSessions: false
-  });
-  if (!res.ok) {
-    const message = (await res.json().catch(() => null))?.message;
-    throw new Error(message ?? `Failed to change password (${String(res.status)}).`);
+
+// src/auth.ts
+var PENDING_SECONDS = 10 * 60;
+var DEFAULT_SESSION_SECONDS = 30 * 24 * 60 * 60;
+var BACK_CHANNEL_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+var ACCOUNT_DELETED_EVENT = "urn:sovereignfs:event:account-deleted";
+var SKEW_SECONDS = 60;
+var Auth = class {
+  #o;
+  #secure;
+  #config;
+  constructor(options) {
+    this.#o = options;
+    this.#secure = new URL(options.appUrl).protocol === "https:";
   }
-}
-async function listSessions() {
-  const [listRes, sessionRes] = await Promise.all([
-    authFetch("/api/auth/list-sessions", "GET"),
-    authFetch("/api/auth/get-session", "GET")
-  ]);
-  if (!listRes.ok) {
-    throw await authError(listRes, "Failed to list sessions");
-  }
-  const raw = await listRes.json();
-  const currentToken = sessionRes.ok ? (await sessionRes.json())?.session?.token ?? null : null;
-  return markCurrentSessions(raw, currentToken);
-}
-async function revokeSession(token) {
-  const res = await authFetch("/api/auth/revoke-session", "POST", { token });
-  if (!res.ok) {
-    throw await authError(res, "Failed to revoke session");
+  /** The app's own callback address, which must be registered with core. */
+  get redirectUri() {
+    return new URL(this.#o.redirectPath, this.#o.appUrl).toString();
   }
-}
-async function signOut() {
-  const res = await authFetch("/api/auth/sign-out", "POST", {});
-  if (!res.ok) {
-    throw await authError(res, "Failed to sign out");
+  /** The address core sends the person to after signing out, which must be registered with core. */
+  get postLogoutRedirectUri() {
+    return new URL(this.#o.postLogoutPath, this.#o.appUrl).toString();
   }
-}
-
-// src/activity.ts
-import { headers as headers2 } from "next/headers";
-
-// src/host.ts
-var HOST_KEY = /* @__PURE__ */ Symbol.for("@sovereignfs/sdk:host");
-function holder() {
-  return globalThis;
-}
-function provideHost(host) {
-  holder()[HOST_KEY] = host;
-}
-function requireHost() {
-  const host = holder()[HOST_KEY];
-  if (!host) {
-    throw new Error(
-      "@sovereignfs/sdk: no runtime host is registered. SDK methods run inside the Sovereign runtime \u2014 start the platform with `pnpm dev` or `pnpm sv dev` and ensure the plugin is installed."
+  // ---- signing in ----------------------------------------------------------------
+  /** Starts a sign-in: the address to send the person to, and the cookie that names what to remember. */
+  async beginSignIn(options = {}) {
+    const config = await this.#configuration();
+    const verifier = client.randomPKCECodeVerifier();
+    const state = client.randomState();
+    const nonce = client.randomNonce();
+    const url2 = client.buildAuthorizationUrl(config, {
+      redirect_uri: this.redirectUri,
+      scope: this.#o.scopes.join(" "),
+      code_challenge: await client.calculatePKCECodeChallenge(verifier),
+      code_challenge_method: "S256",
+      state,
+      nonce
+    });
+    const id = newId();
+    await this.#o.sessionStore.set(
+      id,
+      { kind: "pending", data: { verifier, state, nonce, returnTo: localPath(options.returnTo) } },
+      this.#now() + PENDING_SECONDS * 1e3
     );
+    return {
+      url: url2.toString(),
+      setCookies: [
+        setCookie(cookieName("signin", this.#secure), id, {
+          secure: this.#secure,
+          maxAgeSeconds: PENDING_SECONDS
+        })
+      ]
+    };
   }
-  return host;
-}
-
-// src/activity.ts
-var activity = {
-  async log(entry) {
-    const h = await headers2();
-    const actorId = h.get("x-sovereign-user-id");
-    const pluginId = h.get("x-sovereign-plugin-id");
-    await requireHost().activity.log(entry, actorId, pluginId);
+  /** Finishes a sign-in at the callback: checks what came back, and makes the session. */
+  async completeSignIn(request) {
+    const pendingName = cookieName("signin", this.#secure);
+    const pendingId = readCookies(request.headers.get("cookie"))[pendingName];
+    const clearPending = clearCookie(pendingName, this.#secure);
+    if (!pendingId) throw new SignInError("No sign-in is in progress.");
+    const pending = await this.#o.sessionStore.get(pendingId);
+    await this.#o.sessionStore.delete(pendingId);
+    if (!pending || pending.kind !== "pending") throw new SignInError("That sign-in has run out.");
+    const config = await this.#configuration();
+    const given = new URL(request.url);
+    const current = new URL(`${given.pathname}${given.search}`, this.#o.appUrl);
+    let tokens;
+    try {
+      tokens = await client.authorizationCodeGrant(config, current, {
+        pkceCodeVerifier: String(pending.data.verifier),
+        expectedState: String(pending.data.state),
+        expectedNonce: String(pending.data.nonce),
+        idTokenExpected: true
+      });
+    } catch (error) {
+      throw this.#failure(error);
+    }
+    const claims = tokens.claims();
+    const sub = claims?.sub;
+    if (!claims || typeof sub !== "string") throw new SignInError("Core gave no identity.");
+    const sid = typeof claims.sid === "string" ? claims.sid : void 0;
+    const seconds = this.#o.sessionSeconds ?? DEFAULT_SESSION_SECONDS;
+    const expiresAt = this.#now() + seconds * 1e3;
+    const scopes = (tokens.scope ?? "").split(" ").filter((scope) => scope !== "");
+    const id = newId();
+    await this.#o.sessionStore.set(
+      id,
+      {
+        kind: "session",
+        sub,
+        ...sid ? { sid } : {},
+        data: { claims, scopes, idToken: tokens.id_token, expiresAt }
+      },
+      expiresAt
+    );
+    await this.#keepRefreshToken(sub, tokens.refresh_token);
+    return {
+      session: sessionFrom(id, {
+        kind: "session",
+        sub,
+        ...sid ? { sid } : {},
+        data: { claims, scopes, expiresAt }
+      }).session,
+      returnTo: localPath(String(pending.data.returnTo)),
+      setCookies: [
+        setCookie(cookieName("session", this.#secure), id, {
+          secure: this.#secure,
+          maxAgeSeconds: seconds
+        }),
+        clearPending
+      ]
+    };
   }
-};
-
-// src/connections.ts
-import { headers as headers3 } from "next/headers";
-var DEFAULT_TENANT_ID2 = "default";
-function parseCapabilities(raw) {
-  if (!raw) return [];
-  try {
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed.filter((cap) => typeof cap === "string") : [];
-  } catch {
-    return [];
+  // ---- the session -----------------------------------------------------------------
+  /** The current session, or nothing. It makes no call to core: the session is the app's own. */
+  async getSession(request) {
+    return (await this.#find(request))?.session ?? null;
   }
-}
-async function connectionContext() {
-  const h = await headers3();
-  const pluginId = h.get("x-sovereign-plugin-id");
-  if (!pluginId) {
-    throw new Error(
-      "sdk.connections requires a plugin route context (x-sovereign-plugin-id header missing)."
+  /** The current session, or `NotAuthenticatedError`. */
+  async requireSession(request) {
+    const session = await this.getSession(request);
+    if (!session) throw new NotAuthenticatedError();
+    return session;
+  }
+  /**
+   * Ends the app's session and clears its cookie, and gives the address of core's sign-out, which ends the person's core
+   * session too. It ends the app's session even if the person never returns from core.
+   */
+  async signOut(request) {
+    const name = cookieName("session", this.#secure);
+    const found = await this.#find(request);
+    const cookies = [clearCookie(name, this.#secure)];
+    if (!found) return { url: this.postLogoutRedirectUri, setCookies: cookies };
+    await this.#o.sessionStore.delete(found.id);
+    const config = await this.#configuration();
+    const hint = found.record.data.idToken;
+    if (!config.serverMetadata().end_session_endpoint || typeof hint !== "string") {
+      return { url: this.postLogoutRedirectUri, setCookies: cookies };
+    }
+    const url2 = client.buildEndSessionUrl(config, {
+      id_token_hint: hint,
+      post_logout_redirect_uri: this.postLogoutRedirectUri
+    });
+    return { url: url2.toString(), setCookies: cookies };
+  }
+  // ---- logout notices --------------------------------------------------------------
+  /** Verifies a logout token from core and ends the sessions it names (sdk §9.1). */
+  async handleBackChannelLogout(request) {
+    const refuse = () => new Response(JSON.stringify({ error: "invalid_request" }), {
+      status: 400,
+      headers: { "content-type": "application/json", "cache-control": "no-store" }
+    });
+    if (request.method !== "POST") return refuse();
+    let token;
+    try {
+      token = new URLSearchParams(await request.text()).get("logout_token");
+    } catch {
+      return refuse();
+    }
+    if (!token) return refuse();
+    const verified = await this.#verifyLogoutToken(token).catch((error) => {
+      if (error instanceof CoreUnavailableError) throw error;
+      return void 0;
+    });
+    if (!verified) return refuse();
+    const store = this.#o.sessionStore;
+    await store.set(
+      `seen:${verified.jti}`,
+      { kind: "seen", data: {} },
+      Math.max(verified.exp * 1e3, this.#now()) + 1e3
+    );
+    await store.deleteMatching(
+      verified.sid ? { sid: verified.sid } : { sub: verified.sub }
+    );
+    return new Response(null, { status: 200, headers: { "cache-control": "no-store" } });
+  }
+  /**
+   * Handles core's account-deleted notice (sdk §9.1, core-app §4.5): the person deleted their account, and the app must delete what it
+   * holds of them. The token is refused, `400` and `invalid_request`, by the rules of a logout token for its own type and event. For a
+   * good one the SDK ends the person's sessions and forgets their stored refresh token (when the token store can), runs `handler`, and
+   * answers `200` only after it has resolved. When the handler throws it answers `500` and says nothing of why, and core sends the
+   * notice again, so the handler must be safe to run twice.
+   */
+  async handleAccountDeleted(request, handler) {
+    const reply = (status, error) => new Response(error ? JSON.stringify({ error }) : null, {
+      status,
+      headers: { "content-type": "application/json", "cache-control": "no-store" }
+    });
+    if (request.method !== "POST") return reply(400, "invalid_request");
+    let token;
+    try {
+      token = new URLSearchParams(await request.text()).get("account_deleted_token");
+    } catch {
+      return reply(400, "invalid_request");
+    }
+    if (!token) return reply(400, "invalid_request");
+    const verified = await this.#verifyNotice(
+      token,
+      "account-deleted+jwt",
+      ACCOUNT_DELETED_EVENT
+    ).catch((error) => {
+      if (error instanceof CoreUnavailableError) throw error;
+      return void 0;
+    });
+    if (!verified?.sub) return reply(400, "invalid_request");
+    const store = this.#o.sessionStore;
+    await store.set(
+      `seen:${verified.jti}`,
+      { kind: "seen", data: {} },
+      Math.max(verified.exp * 1e3, this.#now()) + 1e3
     );
+    await store.deleteMatching({ sub: verified.sub });
+    await this.#o.tokenStore?.delete?.(verified.sub);
+    try {
+      await handler({ sub: verified.sub });
+    } catch {
+      return reply(500, "server_error");
+    }
+    return reply(200);
+  }
+  async #verifyLogoutToken(token) {
+    return this.#verifyNotice(token, "logout+jwt", BACK_CHANNEL_EVENT);
+  }
+  /** Checks a notice core signed (a logout token or an account-deleted token): the same rules, for its own type and event. */
+  async #verifyNotice(token, typ, event) {
+    const config = await this.#configuration();
+    const jwksUri = config.serverMetadata().jwks_uri;
+    if (!jwksUri) return void 0;
+    const keys = createRemoteJWKSet(new URL(jwksUri), {
+      [joseFetch]: (url2, init) => this.#o.transport.send(url2, init, {
+        operation: "jwks",
+        safeToRepeat: true,
+        deadline: this.#o.transport.deadline()
+      })
+    });
+    let payload;
+    try {
+      ({ payload } = await jwtVerify(token, keys, {
+        issuer: this.#o.coreUrl,
+        audience: this.#o.clientId,
+        typ,
+        currentDate: new Date(this.#now()),
+        requiredClaims: ["iat", "exp", "jti"]
+      }));
+    } catch (error) {
+      if (error instanceof CoreUnavailableError) throw error;
+      if (error instanceof joseErrors.JOSEError) return void 0;
+      if (error instanceof Error && error.name === "JWKSTimeout") {
+        throw new CoreUnavailableError("Core\u2019s keys could not be fetched.");
+      }
+      return void 0;
+    }
+    const now = Math.floor(this.#now() / 1e3);
+    if (typeof payload.iat !== "number" || payload.iat > now + SKEW_SECONDS) return void 0;
+    const events = payload.events;
+    if (!events || typeof events !== "object" || !(event in events)) return void 0;
+    if ("nonce" in payload) return void 0;
+    const sub = typeof payload.sub === "string" && payload.sub !== "" ? payload.sub : void 0;
+    const sid = typeof payload.sid === "string" && payload.sid !== "" ? payload.sid : void 0;
+    if (!sub && !sid) return void 0;
+    const jti = payload.jti;
+    if (await this.#o.sessionStore.get(`seen:${jti}`)) return void 0;
+    return { sub, sid, jti, exp: payload.exp };
+  }
+  // ---- inside ------------------------------------------------------------------------
+  async #find(request) {
+    const id = readCookies(request.headers.get("cookie"))[cookieName("session", this.#secure)];
+    if (!id) return null;
+    const record = await this.#o.sessionStore.get(id);
+    if (!record || record.kind !== "session") return null;
+    const { session } = sessionFrom(id, record);
+    if (session.expiresAt <= this.#now()) return null;
+    return { id, record, session };
+  }
+  /** The person's refresh token goes to the token store, so the app can call core as them (sdk §5.1). */
+  async #keepRefreshToken(sub, refresh) {
+    const store = this.#o.tokenStore;
+    if (!store || !refresh) return;
+    try {
+      await store.write(sub, refresh, await store.read(sub));
+    } catch {
+    }
+  }
+  #now() {
+    return this.#o.transport.environment.now();
   }
+  #configuration() {
+    this.#config ??= this.#discover().catch((error) => {
+      this.#config = void 0;
+      throw error;
+    });
+    return this.#config;
+  }
+  async #discover() {
+    const transport = this.#o.transport;
+    const send = (url2, options) => transport.send(url2, options, {
+      operation: "sign-in",
+      safeToRepeat: options.method === "GET",
+      deadline: transport.deadline()
+    });
+    const insecure = new URL(this.#o.coreUrl).protocol === "http:";
+    try {
+      const config = await client.discovery(
+        new URL(this.#o.coreUrl),
+        this.#o.clientId,
+        void 0,
+        client.ClientSecretBasic(this.#o.clientSecret),
+        {
+          ...insecure ? { execute: [client.allowInsecureRequests] } : {},
+          [client.customFetch]: send
+        }
+      );
+      config[client.customFetch] = send;
+      return config;
+    } catch (error) {
+      throw this.#failure(error);
+    }
+  }
+  /** What went wrong, as the family of errors says it: core unreachable, or a sign-in that did not check out. */
+  #failure(error) {
+    if (error instanceof CoreUnavailableError) return error;
+    const cause = error?.cause;
+    if (cause instanceof CoreUnavailableError) return cause;
+    return new SignInError("Core did not accept the sign-in. Start again.", { cause: error });
+  }
+};
+function sessionFrom(id, record) {
+  const data = record.data;
+  const claims = data.claims ?? {};
+  const roles = Array.isArray(claims.roles) ? claims.roles.filter((role) => typeof role === "string") : [];
   return {
-    tenantId: DEFAULT_TENANT_ID2,
-    pluginId,
-    userId: h.get("x-sovereign-user-id"),
-    capabilities: parseCapabilities(h.get("x-sovereign-user-capabilities"))
+    id,
+    session: {
+      sub: String(record.sub),
+      sid: record.sid,
+      claims,
+      scopes: data.scopes ?? [],
+      roles,
+      expiresAt: Number(data.expiresAt ?? 0)
+    }
   };
 }
-function requireUserForUserScope(scope, userId) {
-  if ((scope === void 0 || scope === "user") && !userId) throw new NotAuthenticatedError();
-}
-var connections = {
-  async create(input) {
-    const context = await connectionContext();
-    requireUserForUserScope(input.scope, context.userId);
-    return requireHost().connections.create(input, context);
-  },
-  async list(filter) {
-    const context = await connectionContext();
-    requireUserForUserScope(filter?.scope, context.userId);
-    return requireHost().connections.list(filter, context);
-  },
-  async get(id) {
-    const context = await connectionContext();
-    return requireHost().connections.get(id, context);
-  },
-  async update(id, input) {
-    const context = await connectionContext();
-    return requireHost().connections.update(id, input, context);
-  },
-  async disconnect(id) {
-    const context = await connectionContext();
-    return requireHost().connections.disconnect(id, context);
-  },
-  async markUsed(id) {
-    const context = await connectionContext();
-    return requireHost().connections.markUsed(id, context);
-  },
-  async markError(id, input) {
-    const context = await connectionContext();
-    return requireHost().connections.markError(id, input, context);
-  },
-  async createOAuthState(input) {
-    const context = await connectionContext();
-    requireUserForUserScope("user", context.userId);
-    return requireHost().connections.createOAuthState(input, context);
-  },
-  async verifyOAuthState(state) {
-    const context = await connectionContext();
-    requireUserForUserScope("user", context.userId);
-    return requireHost().connections.verifyOAuthState(state, context);
-  },
-  async getProviderConfig(provider) {
-    const context = await connectionContext();
-    return requireHost().connections.getProviderConfig(provider, context);
-  }
-};
 
-// src/data.ts
-import { headers as headers4 } from "next/headers";
-var DEFAULT_TENANT_ID3 = "default";
-var data = {
-  /**
-   * Provider: register a resolver for one of the contracts this plugin exposes.
-   * Call this before any consumer can query the contract — typically at the top
-   * of a route handler or server component that runs when the plugin is loaded.
-   * Registrations are in-process and reset on server restart.
-   */
-  provide(contract, resolver) {
-    requireHost().data.provide(contract, resolver);
-  },
-  /** Consumer: read a provider plugin's contract for the current user (consent-gated). */
-  async query(ref, params) {
-    const h = await headers4();
-    const consumerId = h.get("x-sovereign-plugin-id");
-    const userId = h.get("x-sovereign-user-id");
-    if (!userId) throw new ConsentRequiredError();
-    const result = await requireHost().data.query(
-      ref,
-      consumerId,
-      userId,
-      DEFAULT_TENANT_ID3,
-      params
-    );
-    return result;
+// src/instance.ts
+var FRESH_MS = 5 * 6e4;
+var PHASE_ONE = ["directory"];
+var API_VERSION = "v1";
+var Instance = class {
+  #transport;
+  #coreUrl;
+  #served;
+  constructor(transport, coreUrl) {
+    this.#transport = transport;
+    this.#coreUrl = coreUrl;
+  }
+  /** The instance's branding, which is public (`getInstanceBranding`). */
+  async branding(deadline) {
+    const document = await this.#fetch(deadline);
+    this.#remember(document);
+    return document;
+  }
+  /** Throws `NotSupportedError` when the instance is known not to serve `capability`. */
+  async require(capability, deadline) {
+    const now = this.#transport.environment.now();
+    let served = this.#served;
+    if (!served || now - served.readAt >= FRESH_MS) {
+      try {
+        this.#remember(await this.#fetch(deadline));
+      } catch {
+        return;
+      }
+      served = this.#served;
+    }
+    if (served && !served.capabilities.has(capability)) throw new NotSupportedError(capability);
+  }
+  /** Reads the document again at the next call, since a `404` may mean the instance changed. */
+  forget() {
+    this.#served = void 0;
+  }
+  async #fetch(deadline) {
+    const core = createCoreClient({
+      baseUrl: this.#coreUrl,
+      fetch: (input, init) => this.#transport.send(input, init ?? {}, {
+        operation: "getInstanceBranding",
+        safeToRepeat: true,
+        deadline
+      })
+    });
+    try {
+      return await core.getInstanceBranding();
+    } catch (error) {
+      if (error instanceof CoreApiError2) {
+        throw new CoreApiError(error.status, error.code, error.message, error.retryAfter);
+      }
+      throw error;
+    }
+  }
+  #remember(document) {
+    const api = document.api;
+    const versions = Array.isArray(api?.versions) ? api.versions : void 0;
+    const listed = Array.isArray(api?.capabilities) ? api.capabilities : void 0;
+    const capabilities = api === void 0 || listed === void 0 ? PHASE_ONE : versions && !versions.includes(API_VERSION) ? [] : listed.filter((name) => typeof name === "string");
+    this.#served = {
+      capabilities: new Set(capabilities),
+      readAt: this.#transport.environment.now()
+    };
   }
 };
 
-// src/directory.ts
-import { headers as headers5 } from "next/headers";
-var DEFAULT_TENANT_ID4 = "default";
-var directory = {
-  /**
-   * Search active users in the current tenant by display name or email.
-   * Results include only display-safe profile fields.
-   */
-  async searchUsers(input) {
-    const h = await headers5();
-    const userId = h.get("x-sovereign-user-id");
-    if (!userId) throw new NotAuthenticatedError();
-    return requireHost().directory.searchUsers(input, userId, DEFAULT_TENANT_ID4);
-  },
-  /**
-   * Resolve explicit user IDs already stored by a plugin into display-safe
-   * profile rows for active users.
-   */
-  async resolveUsers(input) {
-    const h = await headers5();
-    const userId = h.get("x-sovereign-user-id");
-    if (!userId) throw new NotAuthenticatedError();
-    return requireHost().directory.resolveUsers(input, userId, DEFAULT_TENANT_ID4);
+// ../config/dist/errors.js
+var ConfigError = class extends Error {
+  problems;
+  name = "ConfigError";
+  constructor(problems) {
+    const count = problems.length;
+    const lines = problems.map((p) => `  - ${p.variable} ${p.message}`);
+    super(`Invalid configuration (${count} ${count === 1 ? "problem" : "problems"}):
+${lines.join("\n")}`);
+    this.problems = problems;
   }
 };
 
-// src/db.ts
-var db_exports = {};
-__export(db_exports, {
-  getClient: () => getClient
-});
-import { headers as headers6 } from "next/headers";
-async function getClient() {
-  let pluginId = null;
-  try {
-    const h = await headers6();
-    pluginId = h.get("x-sovereign-plugin-id");
-  } catch {
+// ../config/dist/define.js
+var PREFIX = /^[A-Z][A-Z0-9]*$/;
+var NAME = /^[A-Z][A-Z0-9_]*$/;
+var FILE_SUFFIX = "_FILE";
+function defineConfig(options) {
+  const { prefix, variables } = options;
+  if (!PREFIX.test(prefix)) {
+    throw new TypeError(`The config prefix "${prefix}" must be upper-case letters and digits, starting with a letter.`);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const [key, variable] of Object.entries(variables)) {
+    if (!NAME.test(variable.name)) {
+      throw new TypeError(`The variable name "${variable.name}" (${key}) must be upper-case letters, digits and underscores, starting with a letter.`);
+    }
+    if (variable.name.endsWith(FILE_SUFFIX)) {
+      throw new TypeError(`The variable name "${variable.name}" (${key}) ends in ${FILE_SUFFIX}, which is reserved for the file form of a secret.`);
+    }
+    const full = `${prefix}_${variable.name}`;
+    const other = seen.get(full);
+    if (other !== void 0)
+      throw new TypeError(`${full} is declared twice (${other} and ${key}).`);
+    seen.set(full, key);
   }
-  return requireHost().db.getClient(pluginId);
+  const entries = Object.entries(variables);
+  return {
+    prefix,
+    load(env = process.env, loadOptions = {}) {
+      const readFile = loadOptions.readFile ?? defaultReadFile;
+      const problems = [];
+      const values = {};
+      for (const [key, variable] of entries) {
+        const full = `${prefix}_${variable.name}`;
+        const source = variable.secret ? readSecret(full, env, readFile, problems) : readPlain(full, env);
+        if (source === void 0)
+          continue;
+        const result = variable.resolve(source.value);
+        if (result.ok) {
+          values[key] = result.value;
+          continue;
+        }
+        const hint = variable.secret && source.value === void 0 ? ` (or set ${full}${FILE_SUFFIX})` : "";
+        problems.push({ variable: source.variable, message: `${result.message}${hint}` });
+      }
+      if (problems.length > 0)
+        throw new ConfigError(problems);
+      return values;
+    },
+    describe() {
+      return entries.map(([key, variable]) => {
+        const full = `${prefix}_${variable.name}`;
+        const row = {
+          key,
+          variable: full,
+          kind: variable.kind,
+          secret: variable.secret,
+          required: variable.required
+        };
+        if (variable.secret)
+          row.fileVariable = `${full}${FILE_SUFFIX}`;
+        if (variable.hasDefault && !variable.secret)
+          row.default = variable.default;
+        if (variable.choices)
+          row.choices = variable.choices;
+        if (variable.description !== void 0)
+          row.description = variable.description;
+        return row;
+      });
+    }
+  };
 }
-
-// src/e2ee.ts
-import { headers as headers7 } from "next/headers";
-var DEFAULT_TENANT_ID5 = "default";
-async function e2eeContext() {
-  const h = await headers7();
-  const userId = h.get("x-sovereign-user-id");
-  if (!userId) throw new NotAuthenticatedError();
-  return { tenantId: DEFAULT_TENANT_ID5, userId };
+function readPlain(full, env) {
+  const raw = env[full]?.trim();
+  return { value: raw === void 0 || raw === "" ? void 0 : raw, variable: full };
 }
-var e2ee = {
-  async getProfile() {
-    const context = await e2eeContext();
-    return requireHost().e2ee.getProfile(context);
-  },
-  async createProfile(input) {
-    const context = await e2eeContext();
-    return requireHost().e2ee.createProfile(input, context);
-  },
-  async getRecoveryWrapper() {
-    const context = await e2eeContext();
-    return requireHost().e2ee.getRecoveryWrapper(context);
-  },
-  async setRecoveryWrapper(input) {
-    const context = await e2eeContext();
-    return requireHost().e2ee.setRecoveryWrapper(input, context);
-  },
-  async enrollDevice(input) {
-    const context = await e2eeContext();
-    return requireHost().e2ee.enrollDevice(input, context);
-  },
-  async listDevices() {
-    const context = await e2eeContext();
-    return requireHost().e2ee.listDevices(context);
-  },
-  async revokeDevice(id) {
-    const context = await e2eeContext();
-    return requireHost().e2ee.revokeDevice(id, context);
+function readSecret(full, env, readFile, problems) {
+  const fileVariable = `${full}${FILE_SUFFIX}`;
+  const direct = env[full];
+  const directSet = direct !== void 0 && direct.trim() !== "";
+  const path = env[fileVariable]?.trim();
+  const fileSet = path !== void 0 && path !== "";
+  if (directSet && fileSet) {
+    problems.push({
+      variable: full,
+      message: `is set together with ${fileVariable}; set only one`
+    });
+    return void 0;
   }
-};
+  if (fileSet) {
+    let content;
+    try {
+      content = readFile(path);
+    } catch {
+      problems.push({ variable: fileVariable, message: "names a file that cannot be read" });
+      return void 0;
+    }
+    const value = content.replace(/\r?\n$/, "");
+    return value.trim() === "" ? { value: void 0, variable: full } : { value, variable: fileVariable };
+  }
+  return { value: directSet ? direct : void 0, variable: full };
+}
+function defaultReadFile(path) {
+  const fs = process.getBuiltinModule("node:fs");
+  return fs.readFileSync(path, "utf8");
+}
 
-// src/env.ts
-import { headers as headers8 } from "next/headers";
-var env = {
-  async get(key) {
-    const h = await headers8();
-    const pluginId = h.get("x-sovereign-plugin-id");
-    if (!pluginId) return null;
-    const slug = pluginId.replace(/[.-]/g, "_").toUpperCase();
-    return process.env[`SV_PLUGIN_${slug}_${key}`] ?? null;
+// ../config/dist/secret.js
+var REDACTED = "[redacted]";
+var Secret = class {
+  // A private field is not an own property: Object.keys, spread, JSON and
+  // structuredClone never see it.
+  #value;
+  constructor(value) {
+    this.#value = value;
+  }
+  /** The secret itself. Call this only where it is actually used. */
+  reveal() {
+    return this.#value;
+  }
+  get length() {
+    return this.#value.length;
+  }
+  /** Compares without exposing either value, and without stopping at the first difference. */
+  equals(other) {
+    const a = this.#value;
+    const b = other.reveal();
+    let difference = a.length ^ b.length;
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+      difference |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+    }
+    return difference === 0;
+  }
+  toString() {
+    return REDACTED;
+  }
+  toJSON() {
+    return REDACTED;
+  }
+  // What `util.inspect` and `console.log` use. Symbol.for avoids importing node:util.
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return `Secret(${REDACTED})`;
   }
 };
 
-// src/mailer.ts
-var mailer_exports = {};
-__export(mailer_exports, {
-  send: () => send
-});
-async function send(options) {
-  await requireHost().mailer.send(options);
+// ../config/dist/variables.js
+var ok = (value) => ({ ok: true, value });
+var fail = (message) => ({ ok: false, message });
+function make({ kind, options, secret: secret2 = false, choices, parse }) {
+  const required = options.required === true;
+  const hasDefault = options.default !== void 0;
+  return {
+    kind,
+    name: options.name,
+    secret: secret2,
+    required,
+    description: options.description,
+    hasDefault,
+    default: secret2 ? void 0 : options.default,
+    choices,
+    resolve(raw) {
+      if (raw === void 0) {
+        if (required)
+          return fail("is required but not set");
+        return ok(options.default);
+      }
+      return parse(raw);
+    }
+  };
 }
-
-// src/notifications.ts
-function getPluginId(headers13) {
-  return headers13.get("x-sovereign-plugin-id");
+function string(options) {
+  return make({ kind: "string", options, parse: (raw) => ok(raw) });
 }
-var notifications = {
-  /**
-   * Send a notification to a user.
-   *
-   * The `source` and `sourceType` fields are set by the runtime from the
-   * calling plugin's ID (injected via `x-sovereign-plugin-id` header) — plugins
-   * cannot forge sender identity.
-   *
-   * @example
-   * ```ts
-   * await sdk.notifications.send({
-   *   recipientUserId: userId,
-   *   title: 'Your export is ready',
-   *   url: '/myPlugin/exports',
-   *   category: 'info',
-   * });
-   * ```
-   */
-  async send(input, requestHeaders) {
-    const pluginId = requestHeaders ? getPluginId(requestHeaders) ?? "unknown" : "unknown";
-    return requireHost().notifications.send(input, pluginId);
+function url(options) {
+  const protocols = options.protocols ?? ["http:", "https:"];
+  return make({
+    kind: "url",
+    options,
+    parse(raw) {
+      const parsed = parseUrl(raw);
+      if (!parsed)
+        return fail("is not a valid URL");
+      if (!protocols.includes(parsed.protocol))
+        return fail(`must use ${protocols.join(" or ")}`);
+      if (parsed.username || parsed.password) {
+        return fail("must not contain a username or password; use a secret for that");
+      }
+      if (options.origin) {
+        if (parsed.pathname !== "/" && parsed.pathname !== "" || parsed.search || parsed.hash) {
+          return fail("must be an address with no path, query or fragment");
+        }
+        return ok(parsed.origin);
+      }
+      return ok(parsed.origin + trimTrailingSlashes(parsed.pathname) + parsed.search + parsed.hash);
+    }
+  });
+}
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/")
+    end -= 1;
+  return value.slice(0, end);
+}
+function parseUrl(raw) {
+  try {
+    return new URL(raw);
+  } catch {
+    return void 0;
   }
-};
-
-// src/platform.ts
-var platform_exports = {};
-__export(platform_exports, {
-  getConfig: () => getConfig
-});
-async function getConfig() {
-  return requireHost().platform.getConfig();
+}
+function secret(options) {
+  return make({
+    kind: "secret",
+    options,
+    secret: true,
+    parse(raw) {
+      if (options.minLength !== void 0 && raw.length < options.minLength) {
+        return fail(`must be at least ${options.minLength} characters`);
+      }
+      if (options.url) {
+        const parsed = parseUrl(raw);
+        if (!parsed)
+          return fail("is not a valid URL");
+        if (!options.url.protocols.includes(parsed.protocol)) {
+          return fail(`must use ${options.url.protocols.join(" or ")}`);
+        }
+      }
+      return ok(new Secret(raw));
+    }
+  });
 }
 
-// src/plugins.ts
-import { headers as headers9 } from "next/headers";
-function parseCapabilities2(raw) {
-  if (!raw) return [];
+// src/settings.ts
+var hasPrefix = (source) => "prefix" in source;
+function readSettings(source) {
+  if (hasPrefix(source)) return fromPrefix(source);
+  return fromOptions(source);
+}
+function fromPrefix(source) {
+  let config;
   try {
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed.filter((cap) => typeof cap === "string") : [];
-  } catch {
-    return [];
+    config = defineConfig({
+      prefix: source.prefix,
+      variables: {
+        appUrl: url({ name: "URL", required: true }),
+        coreUrl: url({ name: "CORE_URL", required: true, origin: true }),
+        clientId: string({ name: "CORE_CLIENT_ID", required: true }),
+        clientSecret: secret({ name: "CORE_CLIENT_SECRET", required: true })
+      }
+    });
+  } catch (error) {
+    throw new ConfigurationError(
+      error instanceof Error ? error.message : "The prefix cannot be used."
+    );
+  }
+  try {
+    const env = source.env ?? globalThis.process?.env ?? {};
+    const values = config.load(env, source.readFile ? { readFile: source.readFile } : {});
+    return checked({
+      appUrl: values.appUrl,
+      coreUrl: values.coreUrl,
+      clientId: values.clientId,
+      clientSecret: values.clientSecret.reveal()
+    });
+  } catch (error) {
+    if (error instanceof ConfigError) throw new ConfigurationError(error.message);
+    throw error;
   }
 }
-async function requestContext() {
-  const h = await headers9();
-  return {
-    userId: h.get("x-sovereign-user-id"),
-    capabilities: parseCapabilities2(h.get("x-sovereign-user-capabilities"))
+function fromOptions(source) {
+  const given = {
+    appUrl: source.appUrl,
+    coreUrl: source.coreUrl,
+    clientId: source.clientId,
+    clientSecret: source.clientSecret
+  };
+  const problems = [];
+  for (const [name, value] of Object.entries(given)) {
+    if (typeof value !== "string" || value.trim() === "") problems.push(`${name} is required`);
+  }
+  if (problems.length > 0) throw problemsOf(problems);
+  return checked(given);
+}
+function checked(settings) {
+  const problems = [];
+  const origin = (name, value, bare) => {
+    try {
+      const parsed = new URL(value);
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        problems.push(`${name} must be an http or https address`);
+      } else if (bare && (parsed.pathname !== "/" || parsed.search !== "" || parsed.hash !== "")) {
+        problems.push(`${name} must have no path: it is the instance's own address`);
+      }
+      return bare ? parsed.origin : parsed.toString();
+    } catch {
+      problems.push(`${name} is not an address`);
+      return value;
+    }
   };
+  const appUrl = origin("the app address", settings.appUrl, false);
+  const coreUrl = origin("the core address", settings.coreUrl, true);
+  if (settings.clientId.trim() === "") problems.push("the client id is required");
+  if (settings.clientSecret.trim() === "") problems.push("the client secret is required");
+  if (problems.length > 0) throw problemsOf(problems);
+  return { appUrl, coreUrl, clientId: settings.clientId, clientSecret: settings.clientSecret };
 }
-var plugins = {
-  /** Discover one installed plugin's status. `null` when not installed. */
-  async get(id) {
-    const { userId, capabilities } = await requestContext();
-    return requireHost().plugins.get(id, userId, capabilities);
-  },
-  /** Discover installed plugins, optionally filtered to those providing a contract. */
-  async list(filter) {
-    const { userId, capabilities } = await requestContext();
-    return requireHost().plugins.list(filter, userId, capabilities);
-  },
-  /** Whether the current user has granted this plugin's requested data contract. */
-  async getConsentStatus(ref) {
-    const h = await headers9();
-    const consumerId = h.get("x-sovereign-plugin-id");
-    const userId = h.get("x-sovereign-user-id");
-    if (!consumerId || !userId) return "not_granted";
-    return requireHost().plugins.getConsentStatus(ref, consumerId, userId);
+function problemsOf(problems) {
+  return new ConfigurationError(
+    `The Sovereign client is configured wrongly (${problems.length} ${problems.length === 1 ? "problem" : "problems"}):
+${problems.map((problem) => `  - ${problem}`).join("\n")}`
+  );
+}
+
+// src/transport.ts
+var SYSTEM = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  random: () => Math.random()
+};
+var DEFAULT_TIMEOUT_MS = 5e3;
+var OVERALL_LIMIT_MS = 1e4;
+var RETRIES = 2;
+var BACKOFF_MS = 200;
+var Transport = class {
+  #fetch;
+  #timeoutMs;
+  #logger;
+  #env;
+  constructor(options = {}) {
+    this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#logger = options.logger;
+    this.#env = options.environment ?? SYSTEM;
+  }
+  get environment() {
+    return this.#env;
+  }
+  get timeoutMs() {
+    return this.#timeoutMs;
+  }
+  /** A deadline for a call that starts now. */
+  deadline() {
+    return this.#env.now() + OVERALL_LIMIT_MS;
+  }
+  /** `fetch` for one request of an operation, retrying as the specification says. */
+  async send(input, init, meta) {
+    let tries = 0;
+    let waited429 = false;
+    for (; ; ) {
+      const started = this.#env.now();
+      const remaining = meta.deadline - started;
+      if (remaining <= 0) {
+        throw new CoreUnavailableError("Core did not answer in time.", { requestSent: false });
+      }
+      let unavailable;
+      try {
+        const reply = await this.#fetch(input, {
+          ...init,
+          signal: AbortSignal.timeout(Math.min(this.#timeoutMs, remaining))
+        });
+        this.#log(meta.operation, reply.status, started);
+        if (reply.status === 429 && !waited429) {
+          const wait = secondsOf(reply.headers.get("retry-after")) * 1e3;
+          if (wait > 0 && this.#env.now() + wait < meta.deadline) {
+            waited429 = true;
+            await reply.body?.cancel().catch(() => void 0);
+            await this.#env.sleep(wait);
+            continue;
+          }
+        }
+        if (reply.status < 500) return reply;
+        await reply.body?.cancel().catch(() => void 0);
+        unavailable = new CoreUnavailableError(`Core answered ${reply.status}.`, {
+          status: reply.status
+        });
+      } catch (error) {
+        if (error instanceof CoreUnavailableError) throw error;
+        this.#log(meta.operation, "error", started);
+        unavailable = new CoreUnavailableError(describe(error), {
+          cause: error,
+          requestSent: !neverSent(error)
+        });
+      }
+      if (!meta.safeToRepeat || tries >= RETRIES) throw unavailable;
+      const pause = BACKOFF_MS * 2 ** tries * (0.5 + this.#env.random());
+      if (this.#env.now() + pause >= meta.deadline) throw unavailable;
+      tries += 1;
+      await this.#env.sleep(pause);
+    }
+  }
+  #log(operation, status, started) {
+    if (!this.#logger) return;
+    try {
+      this.#logger({ operation, status, durationMs: Math.max(0, this.#env.now() - started) });
+    } catch {
+    }
   }
 };
+function secondsOf(header) {
+  const seconds = Number(header);
+  return header !== null && Number.isFinite(seconds) && seconds > 0 ? seconds : 0;
+}
+function describe(error) {
+  if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+    return "Core did not answer in time.";
+  }
+  return "Core could not be reached.";
+}
+var NEVER_SENT = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+function neverSent(error) {
+  for (let current = error, depth = 0; current && depth < 4; depth += 1) {
+    const code = current.code;
+    if (typeof code === "string" && NEVER_SENT.has(code)) return true;
+    current = current.cause;
+  }
+  return false;
+}
 
-// src/portability.ts
-import { headers as headers10 } from "next/headers";
-var portability = {
-  /** Provider: register this plugin's export resolver. */
-  async provideExport(resolver) {
-    const pluginId = (await headers10()).get("x-sovereign-plugin-id");
-    if (!pluginId) {
-      throw new Error(
-        "sdk.portability.provideExport() must be called from a plugin route context (x-sovereign-plugin-id header missing)."
+// src/tokens.ts
+var EARLY_MS = 3e4;
+var keyOf = (actor) => actor.kind === "person" ? `person:${actor.sub}` : "app";
+var TokenManager = class {
+  #options;
+  #cache = /* @__PURE__ */ new Map();
+  #flights = /* @__PURE__ */ new Map();
+  /** Refresh tokens that core has probably rotated away, by person: sending one again would look like theft. */
+  #lost = /* @__PURE__ */ new Map();
+  #endpoint;
+  constructor(options) {
+    this.#options = options;
+  }
+  /** An access token for the Core API for this actor, from the cache when it is good. */
+  token(actor, deadline) {
+    const key = keyOf(actor);
+    const cached = this.#cache.get(key);
+    if (cached && cached.expiresAt - EARLY_MS > this.#options.transport.environment.now()) {
+      return Promise.resolve(cached.token);
+    }
+    const running = this.#flights.get(key);
+    if (running) return running;
+    const flight = (actor.kind === "person" ? this.#refresh(actor.sub, deadline) : this.#appToken(deadline)).finally(() => this.#flights.delete(key));
+    this.#flights.set(key, flight);
+    return flight;
+  }
+  /** Forgets the cached token of an actor, after core said it is no good. */
+  discard(actor) {
+    this.#cache.delete(keyOf(actor));
+  }
+  /** The address of core's token endpoint, from its discovery document, asked for once. */
+  #tokenEndpoint(deadline) {
+    this.#endpoint ??= this.#discover(deadline).catch((error) => {
+      this.#endpoint = void 0;
+      throw error;
+    });
+    return this.#endpoint;
+  }
+  async #discover(deadline) {
+    const reply = await this.#options.transport.send(
+      `${this.#options.coreUrl}/.well-known/openid-configuration`,
+      { method: "GET", headers: { accept: "application/json" } },
+      { operation: "discovery", safeToRepeat: true, deadline }
+    );
+    if (!reply.ok) throw new CoreUnavailableError(`Core answered ${reply.status}.`);
+    const document = await reply.json().catch(() => void 0);
+    if (typeof document?.token_endpoint !== "string") {
+      throw new CoreUnavailableError("Core published no token endpoint.");
+    }
+    return document.token_endpoint;
+  }
+  #request(body, endpoint, deadline, safe) {
+    const { clientId, clientSecret, coreUrl, transport } = this.#options;
+    const basic = btoa(`${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`);
+    return transport.send(
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          "content-type": "application/x-www-form-urlencoded",
+          authorization: `Basic ${basic}`
+        },
+        body: new URLSearchParams({ ...body, resource: `${coreUrl}/api/v1` }).toString()
+      },
+      { operation: "token", safeToRepeat: safe, deadline }
+    );
+  }
+  // ---- a person ----------------------------------------------------------------
+  #refresh(sub, deadline) {
+    const store = this.#options.store;
+    if (!store) {
+      return Promise.reject(
+        new SessionEndedError("No token store was given, so there is no refresh token to use.")
       );
     }
-    requireHost().portability.provideExport(pluginId, resolver);
-  },
-  /** Provider: register this plugin's import handler. */
-  async provideImport(handler) {
-    const pluginId = (await headers10()).get("x-sovereign-plugin-id");
-    if (!pluginId) {
-      throw new Error(
-        "sdk.portability.provideImport() must be called from a plugin route context (x-sovereign-plugin-id header missing)."
+    const work = () => this.#refreshOnce(store, sub, deadline);
+    return store.lock ? store.lock(sub, work) : work();
+  }
+  async #refreshOnce(store, sub, deadline) {
+    const previous = await store.read(sub);
+    if (!previous)
+      throw new SessionEndedError("This person has no refresh token. They must sign in again.");
+    if (this.#lost.get(sub) === previous) {
+      throw new SessionEndedError(
+        "This person\u2019s session was lost in a renewal. They must sign in again."
       );
     }
-    requireHost().portability.provideImport(pluginId, handler);
-  },
-  /** Provider: register this plugin's deletion handler (RFC 0033). */
-  async provideDelete(handler) {
-    const pluginId = (await headers10()).get("x-sovereign-plugin-id");
-    if (!pluginId) {
-      throw new Error(
-        "sdk.portability.provideDelete() must be called from a plugin route context (x-sovereign-plugin-id header missing)."
+    const endpoint = await this.#tokenEndpoint(deadline);
+    let reply;
+    try {
+      reply = await this.#request(
+        { grant_type: "refresh_token", refresh_token: previous },
+        endpoint,
+        deadline,
+        false
+      );
+    } catch (error) {
+      if (error instanceof CoreUnavailableError && (!error.requestSent || error.status !== void 0)) {
+        throw error;
+      }
+      this.#lost.set(sub, previous);
+      throw new SessionEndedError(
+        "Core did not answer the request to renew this person\u2019s session, so it may have been renewed. They must sign in again."
+      );
+    }
+    if (!reply.ok) throw await refusal(reply, true);
+    const answer = await reply.json().catch(() => void 0);
+    const access = answer?.access_token;
+    const lifetime = Number(answer?.expires_in);
+    if (typeof access !== "string" || !Number.isFinite(lifetime)) {
+      throw new SessionEndedError(
+        "Core\u2019s answer to a renewal could not be read. They must sign in again."
+      );
+    }
+    const next = typeof answer?.refresh_token === "string" ? answer.refresh_token : previous;
+    if (next !== previous) {
+      const stored = await (async () => store.write(sub, next, previous))().then(
+        (result) => result === true,
+        () => false
       );
+      if (!stored) {
+        this.#lost.set(sub, previous);
+        throw new SessionEndedError(
+          "The renewed token could not be stored. They must sign in again."
+        );
+      }
     }
-    requireHost().portability.provideDelete(pluginId, handler);
+    this.#cache.set(keyOf({ kind: "person", sub }), {
+      token: access,
+      expiresAt: this.#options.transport.environment.now() + lifetime * 1e3
+    });
+    return access;
+  }
+  // ---- the app -----------------------------------------------------------------
+  async #appToken(deadline) {
+    const endpoint = await this.#tokenEndpoint(deadline);
+    const reply = await this.#request(
+      { grant_type: "client_credentials" },
+      endpoint,
+      deadline,
+      true
+    );
+    if (!reply.ok) throw await refusal(reply, false);
+    const answer = await reply.json().catch(() => void 0);
+    const access = answer?.access_token;
+    const lifetime = Number(answer?.expires_in);
+    if (typeof access !== "string" || !Number.isFinite(lifetime)) {
+      throw new CoreUnavailableError(
+        "Core\u2019s answer to a request for an app token could not be read."
+      );
+    }
+    this.#cache.set("app", {
+      token: access,
+      expiresAt: this.#options.transport.environment.now() + lifetime * 1e3
+    });
+    return access;
   }
 };
-
-// src/secrets.ts
-import { headers as headers11 } from "next/headers";
-var DEFAULT_TENANT_ID6 = "default";
-function parseCapabilities3(raw) {
-  if (!raw) return [];
+async function refusal(reply, person) {
+  let code = "unknown";
+  let message = `Core answered ${reply.status}.`;
   try {
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed.filter((cap) => typeof cap === "string") : [];
+    const body = await reply.json();
+    if (typeof body.error === "string") code = body.error;
+    if (typeof body.error_description === "string") message = body.error_description;
   } catch {
-    return [];
   }
-}
-async function secretContext() {
-  const h = await headers11();
-  const pluginId = h.get("x-sovereign-plugin-id");
-  if (!pluginId) {
-    throw new Error(
-      "sdk.secrets requires a plugin route context (x-sovereign-plugin-id header missing)."
+  if (person && code === "invalid_grant") {
+    return new SessionEndedError(
+      "This person\u2019s session cannot be renewed. They must sign in again."
     );
   }
-  return {
-    tenantId: DEFAULT_TENANT_ID6,
-    pluginId,
-    userId: h.get("x-sovereign-user-id"),
-    capabilities: parseCapabilities3(h.get("x-sovereign-user-capabilities"))
-  };
-}
-function requireUserForUserScope2(scope, userId) {
-  if (scope === "user" && !userId) throw new NotAuthenticatedError();
+  const retryAfter = secondsOf(reply.headers.get("retry-after"));
+  return new CoreApiError(reply.status, code, message, retryAfter > 0 ? retryAfter : void 0);
 }
-var secrets = {
-  async create(input) {
-    const context = await secretContext();
-    requireUserForUserScope2(input.scope, context.userId);
-    return requireHost().secrets.create(input, context);
-  },
-  async get(id) {
-    const context = await secretContext();
-    return requireHost().secrets.get(id, context);
-  },
-  async list(scope) {
-    const context = await secretContext();
-    if (scope) requireUserForUserScope2(scope, context.userId);
-    return requireHost().secrets.list(scope, context);
-  },
-  async update(id, value) {
-    const context = await secretContext();
-    return requireHost().secrets.update(id, value, context);
-  },
-  async delete(id) {
-    const context = await secretContext();
-    return requireHost().secrets.delete(id, context);
-  }
-};
 
-// src/storage.ts
-import { headers as headers12 } from "next/headers";
-var DEFAULT_TENANT_ID7 = "default";
-async function storageContext() {
-  const h = await headers12();
-  const pluginId = h.get("x-sovereign-plugin-id");
-  if (!pluginId) {
-    throw new Error(
-      "sdk.storage requires a plugin route context (x-sovereign-plugin-id header missing)."
-    );
+// src/sovereign.ts
+var CAPABILITY = {
+  searchDirectoryUsers: "directory",
+  resolveDirectoryUsers: "directory",
+  findDirectoryUserByEmail: "directory",
+  sendNotification: "notifications",
+  sendEmail: "email",
+  logActivity: "activity",
+  listNotifications: "notifications",
+  markNotificationRead: "notifications",
+  markAllNotificationsRead: "notifications",
+  dismissNotification: "notifications",
+  dismissAllNotifications: "notifications"
+};
+function createSovereign(options) {
+  const settings = readSettings(options);
+  const transport = new Transport({
+    ...options.fetch ? { fetch: options.fetch } : {},
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+    ...options.logger ? { logger: options.logger } : {},
+    ...options.environment ? { environment: options.environment } : {}
+  });
+  const tokens = new TokenManager({
+    transport,
+    coreUrl: settings.coreUrl,
+    clientId: settings.clientId,
+    clientSecret: settings.clientSecret,
+    store: options.tokenStore
+  });
+  const instance = new Instance(transport, settings.coreUrl);
+  let auth;
+  const pageOf = (path) => new URL(path, settings.coreUrl).toString();
+  async function execute(actor, name, request) {
+    const deadline = transport.deadline();
+    const operation = operations[name];
+    const capability = CAPABILITY[name];
+    if (capability) await instance.require(capability, deadline);
+    for (let attempt = 0; ; attempt += 1) {
+      const token = actor ? await tokens.token(actor, deadline) : void 0;
+      const core = createCoreClient({
+        baseUrl: settings.coreUrl,
+        ...token ? { token } : {},
+        fetch: (input, init) => transport.send(input, init ?? {}, {
+          operation: name,
+          safeToRepeat: operation.safeToRepeat,
+          deadline
+        })
+      });
+      try {
+        const call2 = core[name];
+        return await call2(request);
+      } catch (error) {
+        if (!(error instanceof CoreApiError2)) throw error;
+        if (error.status === 404) instance.forget();
+        if (error.status === 401 && actor) {
+          tokens.discard(actor);
+          if (attempt === 0) continue;
+          if (actor.kind === "person") {
+            throw new SessionEndedError(
+              "Core refused this person\u2019s token twice. They must sign in again."
+            );
+          }
+        }
+        throw new CoreApiError(error.status, error.code, error.message, error.retryAfter);
+      }
+    }
   }
+  const directory = (actor) => ({
+    searchUsers: (query) => execute(actor, "searchDirectoryUsers", { query }),
+    resolveUsers: (body) => execute(actor, "resolveDirectoryUsers", { body }),
+    findUserByEmail: (query) => execute(actor, "findDirectoryUserByEmail", { query })
+  });
+  const notifications = (actor) => ({
+    list: (query) => execute(actor, "listNotifications", query === void 0 ? {} : { query }),
+    markRead: (id) => execute(actor, "markNotificationRead", { params: { id } }),
+    markAllRead: () => execute(actor, "markAllNotificationsRead", void 0),
+    dismiss: (id) => execute(actor, "dismissNotification", { params: { id } }),
+    dismissAll: () => execute(actor, "dismissAllNotifications", void 0)
+  });
   return {
-    tenantId: DEFAULT_TENANT_ID7,
-    pluginId,
-    userId: h.get("x-sovereign-user-id")
+    as(person) {
+      if (typeof person?.sub !== "string" || person.sub === "") {
+        throw new ConfigurationError("A person needs a sub: pass the session or { sub }.");
+      }
+      if (!options.tokenStore) {
+        throw new ConfigurationError(
+          "Calling as a person needs a token store: pass tokenStore when creating the client."
+        );
+      }
+      const actor = { kind: "person", sub: person.sub };
+      return { directory: directory(actor), notifications: notifications(actor) };
+    },
+    app: {
+      notifications: {
+        send: (message) => execute({ kind: "app" }, "sendNotification", { body: message })
+      },
+      email: {
+        sendToUser: (message) => execute({ kind: "app" }, "sendEmail", { body: message })
+      },
+      activity: {
+        log: (entry) => execute({ kind: "app" }, "logActivity", { body: entry })
+      }
+    },
+    get auth() {
+      if (!options.sessionStore) {
+        throw new ConfigurationError(
+          "Signing people in needs a session store: pass sessionStore when creating the client."
+        );
+      }
+      auth ??= new Auth({
+        appUrl: settings.appUrl,
+        coreUrl: settings.coreUrl,
+        clientId: settings.clientId,
+        clientSecret: settings.clientSecret,
+        transport,
+        sessionStore: options.sessionStore,
+        tokenStore: options.tokenStore,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"],
+        redirectPath: options.redirectPath ?? "/auth/callback",
+        postLogoutPath: options.postLogoutPath ?? "/",
+        sessionSeconds: options.sessionSeconds
+      });
+      return auth;
+    },
+    links: {
+      profile: pageOf("/profile"),
+      security: pageOf("/security"),
+      preferences: pageOf("/preferences"),
+      connectedApps: pageOf("/connected-apps"),
+      deleteAccount: pageOf("/delete-account")
+    },
+    instance: {
+      getBranding: () => instance.branding(transport.deadline())
+    }
   };
 }
-var storage = {
-  async put(input) {
-    const context = await storageContext();
-    return requireHost().storage.put(input, context);
-  },
-  async get(key) {
-    const context = await storageContext();
-    return requireHost().storage.get(key, context);
-  },
-  async delete(key) {
-    const context = await storageContext();
-    return requireHost().storage.delete(key, context);
-  },
-  async list(prefix) {
-    const context = await storageContext();
-    return requireHost().storage.list(prefix, context);
-  },
-  /** Create a short-lived, read-only download URL for an object (default 5 minutes, max 1 hour). */
-  async getSignedUrl(key, options) {
-    const context = await storageContext();
-    return requireHost().storage.getSignedUrl(key, options, context);
-  }
-};
-
-// src/unimplemented.ts
-var events = {
-  publish(_event, _payload) {
-    throw new NotImplementedError("sdk.events.publish() is not implemented in Sovereign v1.");
-  },
-  subscribe(_event, _handler) {
-    throw new NotImplementedError("sdk.events.subscribe() is not implemented in Sovereign v1.");
-  }
-};
-var billing = {
-  /**
-   * Returns the current user's active entitlement for the calling plugin, or
-   * `null` when no entitlement exists. Use this to branch UI by tier.
-   */
-  getEntitlement(_headers) {
-    throw new NotImplementedError("sdk.billing.getEntitlement() is not yet implemented.");
-  },
-  /**
-   * Asserts that the current user has an active entitlement for the calling
-   * plugin. Throws `EntitlementRequiredError` when absent. Use for in-plugin
-   * feature gating (route-level access is already gated by the middleware).
-   */
-  requireEntitlement(_headers) {
-    throw new EntitlementRequiredError(
-      "sdk.billing.requireEntitlement() is not yet implemented \u2014 no entitlement check performed."
-    );
-  }
-};
-
-// src/index.ts
-var sdk = {
-  // Stable (v1.0.0).
-  auth: auth_exports,
-  db: db_exports,
-  mailer: mailer_exports,
-  platform: platform_exports,
-  // Experimental / reserved — shape may change; some throw until implemented.
-  data,
-  storage,
-  directory,
-  notifications,
-  secrets,
-  connections,
-  e2ee,
-  events,
-  activity,
-  portability,
-  plugins,
-  env,
-  billing
-};
 export {
-  ConsentRequiredError,
-  EntitlementRequiredError,
+  ConfigurationError,
+  CoreApiError,
+  CoreUnavailableError,
   NotAuthenticatedError,
-  NotImplementedError,
-  provideHost,
-  sdk
+  NotSupportedError,
+  SessionEndedError,
+  SignInError,
+  SovereignError,
+  createSovereign,
+  hasRole
 };