@ai-matrx/auth 0.2.1 → 0.2.2

package/dist/guest.cjs

@@ -0,0 +1,213 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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/guest.ts
+var guest_exports = {};
+__export(guest_exports, {
+  DEFAULT_GUEST_CARRIER_COOKIE: () => DEFAULT_GUEST_CARRIER_COOKIE,
+  createGuestHandover: () => createGuestHandover,
+  createGuestSessionEnsurer: () => createGuestSessionEnsurer,
+  guestClientCookieOptions: () => guestClientCookieOptions,
+  isGuestCookieName: () => isGuestCookieName,
+  looksLikeVisitorId: () => looksLikeVisitorId
+});
+module.exports = __toCommonJS(guest_exports);
+var import_ssr = require("@supabase/ssr");
+var VISITOR_ID = /^[A-Za-z0-9]{16,200}$/;
+function looksLikeVisitorId(id) {
+  return typeof id === "string" && !id.startsWith("temp_") && VISITOR_ID.test(id);
+}
+function isGuestCookieName(guestCookieName, name) {
+  return name === guestCookieName || name.startsWith(`${guestCookieName}.`);
+}
+var DEFAULT_GUEST_CARRIER_COOKIE = "matrx_guest_visitor";
+function createGuestHandover(options) {
+  const carrier = options.carrierCookieName ?? DEFAULT_GUEST_CARRIER_COOKIE;
+  const loud = options.log ?? ((m) => console.error(`[session-handover] LOUD: ${m}`));
+  const isGuestCookie = (name) => isGuestCookieName(options.guestCookieName, name);
+  const msg = (err) => err instanceof Error ? err.message : String(err);
+  async function readClaims(jar) {
+    if (options.readGuestClaims) return options.readGuestClaims(jar);
+    if (!options.supabase) return null;
+    const guest = (0, import_ssr.createServerClient)(options.supabase.url, options.supabase.publishableKey, {
+      cookieOptions: { name: options.guestCookieName },
+      cookies: { getAll: () => jar.getAll(), setAll: () => void 0 }
+    });
+    const { data } = await guest.auth.getClaims();
+    return data?.claims ?? null;
+  }
+  async function readGuestPossession(visitorId) {
+    const jar = await options.cookies();
+    if (jar.getAll().some((c) => isGuestCookie(c.name))) {
+      try {
+        const claims = await readClaims(jar);
+        if (claims?.sub && claims.is_anonymous === true) return { guestId: claims.sub, proof: "guest_session" };
+      } catch (err) {
+        loud(`the guest cookie could not be verified: ${msg(err)}`);
+      }
+    }
+    const candidates = [visitorId, options.visitorCookieName ? jar.get(options.visitorCookieName)?.value : void 0].filter(looksLikeVisitorId);
+    if (!candidates.length) return null;
+    const { data: ids, error } = await options.store.findGuestIdsByVisitor(candidates);
+    if (error) {
+      loud(`the visitor's guest could not be looked up: ${error.message}`);
+      return null;
+    }
+    for (const id of ids ?? []) {
+      if (await options.store.isAnonymousUser(id)) return { guestId: id, proof: "visitor_id" };
+    }
+    return null;
+  }
+  async function dropGuestCookies() {
+    try {
+      const jar = await options.cookies();
+      for (const c of jar.getAll()) if (isGuestCookie(c.name)) jar.delete(c.name);
+    } catch {
+    }
+  }
+  async function claimGuestInto(guest, accountId, via) {
+    if (guest.guestId === accountId) return { status: "same_account" };
+    const { data, error } = await options.store.claimWorkspace({ guestId: guest.guestId, targetId: accountId, via });
+    if (error) {
+      loud(`the guest's records were NOT brought into ${accountId} (${via}); the guest cookie is kept so the next sign-in retries: ${error.message}`);
+      return { status: "failed", guestId: guest.guestId, message: error.message };
+    }
+    await dropGuestCookies();
+    const records = typeof data?.records === "number" ? data.records : 0;
+    return { status: "claimed", guestId: guest.guestId, records };
+  }
+  return {
+    looksLikeVisitorId,
+    readGuestPossession,
+    claimGuestInto,
+    async handOverSession(via, replace, opts = {}) {
+      const guest = await readGuestPossession(opts.visitorId);
+      const result = await replace();
+      const user = result.error ? null : result.data?.user ?? null;
+      let guestClaim = { status: "none" };
+      if (guest && user && user.is_anonymous !== true) guestClaim = await claimGuestInto(guest, user.id, via);
+      return { ...result, guestClaim };
+    },
+    async settlePendingGuestClaim(accountId) {
+      const jar = await options.cookies();
+      if (!jar.getAll().some((c) => isGuestCookie(c.name))) return { status: "none" };
+      const guest = await readGuestPossession(null);
+      if (!guest || guest.proof !== "guest_session") return { status: "none" };
+      return claimGuestInto(guest, accountId, "password_login");
+    },
+    async promoteGuest(args) {
+      const guest = await readGuestPossession(args.visitorId);
+      if (!guest) return { kind: "no_guest" };
+      const revive = async () => {
+        const { error } = await options.store.revive(guest.guestId);
+        if (error) throw new Error(`the guest could not be reopened: ${error.message}`);
+      };
+      try {
+        await revive();
+        const { error } = await options.store.promoteUser(guest.guestId, { email: args.email, password: args.password });
+        if (error) {
+          const m = error.message.toLowerCase();
+          if (error.code === "email_exists" || m.includes("already been registered") || m.includes("already registered") || m.includes("already exists")) {
+            return { kind: "email_in_use" };
+          }
+          loud(`guest promotion failed \u2014 the guest is kept, no new account is made: ${error.message}`);
+          return { kind: "failed", message: error.message };
+        }
+        await revive();
+        const { error: stampErr } = await options.store.stampConverted(guest.guestId);
+        if (stampErr) loud(`promotion succeeded but the registry row was not stamped: ${stampErr.message}`);
+        return { kind: "promoted", userId: guest.guestId };
+      } catch (err) {
+        loud(`guest promotion failed \u2014 the guest is kept: ${msg(err)}`);
+        return { kind: "failed", message: msg(err) };
+      }
+    },
+    finishPromotion: dropGuestCookies,
+    async rememberGuestVisitorId(formData) {
+      try {
+        const id = formData?.get("guestFingerprint")?.toString();
+        if (!looksLikeVisitorId(id)) return;
+        (await options.cookies()).set(carrier, id, {
+          httpOnly: true,
+          sameSite: "lax",
+          secure: options.secureCookies ?? false,
+          path: "/",
+          maxAge: 600
+        });
+      } catch (err) {
+        loud(`the visitor id could not be kept for the OAuth round trip: ${msg(err)}`);
+      }
+    },
+    async takeGuestVisitorId() {
+      const jar = await options.cookies();
+      const id = jar.get(carrier)?.value ?? null;
+      if (id) {
+        try {
+          jar.delete(carrier);
+        } catch {
+        }
+      }
+      return looksLikeVisitorId(id) ? id : null;
+    }
+  };
+}
+function guestClientCookieOptions(cookieName, secure = typeof window !== "undefined" && window.location.protocol === "https:") {
+  return { name: cookieName, path: "/", sameSite: "lax", secure, maxAge: 60 * 60 * 24 * 400 };
+}
+function createGuestSessionEnsurer(options) {
+  const doFetch = options.fetch ?? fetch;
+  let inFlight = null;
+  async function existing() {
+    const { data } = await options.auth.getSession();
+    const user = data.session?.user;
+    if (!user?.is_anonymous) return null;
+    const orgs = [...new Set((await options.listWorkspaceIds(user.id)).filter((o) => typeof o === "string"))];
+    return orgs.length === 1 ? { organizationId: orgs[0], adoptedFrom: null } : null;
+  }
+  async function mint() {
+    const have = await existing();
+    if (have) return have;
+    const base = options.serverBaseUrl;
+    if (!base) throw new Error("The AI Matrx server address is not configured, so a guest session cannot be made.");
+    const fingerprint = await options.getFingerprint();
+    const res = await doFetch(`${base.replace(/\/$/, "")}/auth/guest/session`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ fingerprint })
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      throw new Error(body?.detail?.message ?? `A guest session could not be made (HTTP ${res.status}).`);
+    }
+    const s = await res.json();
+    const { error } = await options.auth.setSession({ access_token: s.access_token, refresh_token: s.refresh_token });
+    if (error) throw new Error(`The guest session could not be kept: ${error.message}`);
+    if (!s.organization_id) throw new Error("The guest session has no workspace to save in.");
+    return { organizationId: s.organization_id, adoptedFrom: s.adopted_from };
+  }
+  return () => {
+    inFlight ??= (async () => {
+      const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+      return locks ? locks.request(options.lockName ?? "matrx-guest-session", () => mint()) : mint();
+    })().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  };
+}

package/dist/guest.d.cts

@@ -0,0 +1,189 @@
+type HandoverVia = "password_login" | "oauth_callback" | "email_otp" | "dev_login" | "sign_up";
+interface GuestPossession {
+    guestId: string;
+    proof: "guest_session" | "visitor_id";
+}
+type GuestClaimOutcome = {
+    status: "none";
+} | {
+    status: "same_account";
+} | {
+    status: "claimed";
+    guestId: string;
+    records: number;
+} | {
+    status: "failed";
+    guestId: string;
+    message: string;
+};
+type GuestPromotion = {
+    kind: "no_guest";
+} | {
+    kind: "promoted";
+    userId: string;
+} | {
+    kind: "email_in_use";
+} | {
+    kind: "failed";
+    message: string;
+};
+/** A guessable `temp_` fallback id is never a proof of possession. */
+declare function looksLikeVisitorId(id: string | null | undefined): id is string;
+/** The guest cookie and its @supabase/ssr chunks (`<name>.0`, `<name>.1`, …). */
+declare function isGuestCookieName(guestCookieName: string, name: string): boolean;
+/** A request's cookie jar (Next's `cookies()` result fits). */
+interface GuestCookieJar {
+    getAll(): {
+        name: string;
+        value: string;
+    }[];
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(name: string, value: string, options?: Record<string, unknown>): unknown;
+    delete(name: string): unknown;
+}
+type DbAnswer<T> = {
+    data: T | null;
+    error: {
+        message: string;
+    } | null;
+};
+/** What the host's server-side store answers (admin/service lane; the host owns the credentials). */
+interface GuestStore {
+    /** Guest user ids the registry bound to any of these visitor ids. */
+    findGuestIdsByVisitor(visitorIds: string[]): Promise<DbAnswer<string[]>>;
+    /** True when the account is an anonymous (guest) one. */
+    isAnonymousUser(userId: string): Promise<boolean>;
+    /** `claim_guest_workspace`: membership moves, no row moves, all or nothing. */
+    claimWorkspace(args: {
+        guestId: string;
+        targetId: string;
+        via: string;
+    }): Promise<DbAnswer<{
+        records?: number;
+        status?: string;
+    }>>;
+    /** `guest_revive`: reopen a guest retention closed. */
+    revive(guestId: string): Promise<DbAnswer<unknown>>;
+    /** Make the guest's account permanent in place. `error.code` may carry `email_exists`. */
+    promoteUser(guestId: string, credentials: {
+        email: string;
+        password: string;
+    }): Promise<{
+        error: {
+            message: string;
+            code?: string;
+        } | null;
+    }>;
+    /** Stamp the registry row converted. */
+    stampConverted(guestId: string): Promise<{
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+interface GuestHandoverOptions {
+    /** The guest session's own cookie name (never the main auth cookie). */
+    guestCookieName: string;
+    /** First-party visitor cookie the guest lane already accepts, if the host has one. */
+    visitorCookieName?: string;
+    /** Short-lived carrier for the visitor id across an OAuth round trip. Default `matrx_guest_visitor`. */
+    carrierCookieName?: string;
+    /** Server cookie jar for this request. */
+    cookies(): Promise<GuestCookieJar>;
+    store: GuestStore;
+    /** Verified claims of the guest cookie. Default: a server client over `supabase` url + key. */
+    readGuestClaims?(jar: GuestCookieJar): Promise<{
+        sub?: string;
+        is_anonymous?: boolean;
+    } | null>;
+    supabase?: {
+        url: string;
+        publishableKey: string;
+    };
+    /** `Secure` on the carrier cookie. */
+    secureCookies?: boolean;
+    log?(message: string): void;
+}
+interface GuestHandover {
+    looksLikeVisitorId: typeof looksLikeVisitorId;
+    readGuestPossession(visitorId?: string | null): Promise<GuestPossession | null>;
+    claimGuestInto(guest: GuestPossession, accountId: string, via: HandoverVia): Promise<GuestClaimOutcome>;
+    handOverSession<R extends {
+        data: {
+            user?: {
+                id: string;
+                is_anonymous?: boolean;
+            } | null;
+        } | null;
+        error: unknown;
+    }>(via: HandoverVia, replace: () => Promise<R>, opts?: {
+        visitorId?: string | null;
+    }): Promise<R & {
+        guestClaim: GuestClaimOutcome;
+    }>;
+    settlePendingGuestClaim(accountId: string): Promise<GuestClaimOutcome>;
+    promoteGuest(args: {
+        email: string;
+        password: string;
+        visitorId?: string | null;
+    }): Promise<GuestPromotion>;
+    finishPromotion(): Promise<void>;
+    rememberGuestVisitorId(formData: FormData | undefined): Promise<void>;
+    takeGuestVisitorId(): Promise<string | null>;
+}
+declare const DEFAULT_GUEST_CARRIER_COOKIE = "matrx_guest_visitor";
+declare function createGuestHandover(options: GuestHandoverOptions): GuestHandover;
+/**
+ * Cookie options for the guest's browser client: its OWN cookie name, never the app singleton's. Pass as
+ * `createBrowserClient(url, key, { isSingleton: false, cookieOptions: guestClientCookieOptions(name) })`.
+ */
+declare function guestClientCookieOptions(cookieName: string, secure?: boolean): {
+    name: string;
+    path: string;
+    sameSite: "lax";
+    secure: boolean;
+    maxAge: number;
+};
+interface GuestSessionAnswer {
+    organizationId: string;
+    adoptedFrom: string | null;
+}
+interface GuestSessionEnsurerOptions {
+    /** The guest browser client's `auth` (its own cookie). */
+    auth: {
+        getSession(): Promise<{
+            data: {
+                session: {
+                    user?: {
+                        id: string;
+                        is_anonymous?: boolean;
+                    };
+                } | null;
+            };
+        }>;
+        setSession(tokens: {
+            access_token: string;
+            refresh_token: string;
+        }): Promise<{
+            error: {
+                message: string;
+            } | null;
+        }>;
+    };
+    /** Workspace (organization) ids the guest belongs to. */
+    listWorkspaceIds(userId: string): Promise<string[]>;
+    /** Base URL of the server that mints guests (`POST <base>/auth/guest/session`). */
+    serverBaseUrl: string | null | undefined;
+    getFingerprint(): Promise<string>;
+    fetch?: typeof fetch;
+    lockName?: string;
+}
+/**
+ * The visitor's guest session, made once. Called on a signed-out visitor's FIRST save or job — never on a
+ * page view. Single flight per tab, and per browser where Web Locks exist (two tabs never mint two guests).
+ */
+declare function createGuestSessionEnsurer(options: GuestSessionEnsurerOptions): () => Promise<GuestSessionAnswer | null>;
+
+export { DEFAULT_GUEST_CARRIER_COOKIE, type GuestClaimOutcome, type GuestCookieJar, type GuestHandover, type GuestHandoverOptions, type GuestPossession, type GuestPromotion, type GuestSessionAnswer, type GuestSessionEnsurerOptions, type GuestStore, type HandoverVia, createGuestHandover, createGuestSessionEnsurer, guestClientCookieOptions, isGuestCookieName, looksLikeVisitorId };

package/dist/guest.d.ts

@@ -0,0 +1,189 @@
+type HandoverVia = "password_login" | "oauth_callback" | "email_otp" | "dev_login" | "sign_up";
+interface GuestPossession {
+    guestId: string;
+    proof: "guest_session" | "visitor_id";
+}
+type GuestClaimOutcome = {
+    status: "none";
+} | {
+    status: "same_account";
+} | {
+    status: "claimed";
+    guestId: string;
+    records: number;
+} | {
+    status: "failed";
+    guestId: string;
+    message: string;
+};
+type GuestPromotion = {
+    kind: "no_guest";
+} | {
+    kind: "promoted";
+    userId: string;
+} | {
+    kind: "email_in_use";
+} | {
+    kind: "failed";
+    message: string;
+};
+/** A guessable `temp_` fallback id is never a proof of possession. */
+declare function looksLikeVisitorId(id: string | null | undefined): id is string;
+/** The guest cookie and its @supabase/ssr chunks (`<name>.0`, `<name>.1`, …). */
+declare function isGuestCookieName(guestCookieName: string, name: string): boolean;
+/** A request's cookie jar (Next's `cookies()` result fits). */
+interface GuestCookieJar {
+    getAll(): {
+        name: string;
+        value: string;
+    }[];
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(name: string, value: string, options?: Record<string, unknown>): unknown;
+    delete(name: string): unknown;
+}
+type DbAnswer<T> = {
+    data: T | null;
+    error: {
+        message: string;
+    } | null;
+};
+/** What the host's server-side store answers (admin/service lane; the host owns the credentials). */
+interface GuestStore {
+    /** Guest user ids the registry bound to any of these visitor ids. */
+    findGuestIdsByVisitor(visitorIds: string[]): Promise<DbAnswer<string[]>>;
+    /** True when the account is an anonymous (guest) one. */
+    isAnonymousUser(userId: string): Promise<boolean>;
+    /** `claim_guest_workspace`: membership moves, no row moves, all or nothing. */
+    claimWorkspace(args: {
+        guestId: string;
+        targetId: string;
+        via: string;
+    }): Promise<DbAnswer<{
+        records?: number;
+        status?: string;
+    }>>;
+    /** `guest_revive`: reopen a guest retention closed. */
+    revive(guestId: string): Promise<DbAnswer<unknown>>;
+    /** Make the guest's account permanent in place. `error.code` may carry `email_exists`. */
+    promoteUser(guestId: string, credentials: {
+        email: string;
+        password: string;
+    }): Promise<{
+        error: {
+            message: string;
+            code?: string;
+        } | null;
+    }>;
+    /** Stamp the registry row converted. */
+    stampConverted(guestId: string): Promise<{
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+interface GuestHandoverOptions {
+    /** The guest session's own cookie name (never the main auth cookie). */
+    guestCookieName: string;
+    /** First-party visitor cookie the guest lane already accepts, if the host has one. */
+    visitorCookieName?: string;
+    /** Short-lived carrier for the visitor id across an OAuth round trip. Default `matrx_guest_visitor`. */
+    carrierCookieName?: string;
+    /** Server cookie jar for this request. */
+    cookies(): Promise<GuestCookieJar>;
+    store: GuestStore;
+    /** Verified claims of the guest cookie. Default: a server client over `supabase` url + key. */
+    readGuestClaims?(jar: GuestCookieJar): Promise<{
+        sub?: string;
+        is_anonymous?: boolean;
+    } | null>;
+    supabase?: {
+        url: string;
+        publishableKey: string;
+    };
+    /** `Secure` on the carrier cookie. */
+    secureCookies?: boolean;
+    log?(message: string): void;
+}
+interface GuestHandover {
+    looksLikeVisitorId: typeof looksLikeVisitorId;
+    readGuestPossession(visitorId?: string | null): Promise<GuestPossession | null>;
+    claimGuestInto(guest: GuestPossession, accountId: string, via: HandoverVia): Promise<GuestClaimOutcome>;
+    handOverSession<R extends {
+        data: {
+            user?: {
+                id: string;
+                is_anonymous?: boolean;
+            } | null;
+        } | null;
+        error: unknown;
+    }>(via: HandoverVia, replace: () => Promise<R>, opts?: {
+        visitorId?: string | null;
+    }): Promise<R & {
+        guestClaim: GuestClaimOutcome;
+    }>;
+    settlePendingGuestClaim(accountId: string): Promise<GuestClaimOutcome>;
+    promoteGuest(args: {
+        email: string;
+        password: string;
+        visitorId?: string | null;
+    }): Promise<GuestPromotion>;
+    finishPromotion(): Promise<void>;
+    rememberGuestVisitorId(formData: FormData | undefined): Promise<void>;
+    takeGuestVisitorId(): Promise<string | null>;
+}
+declare const DEFAULT_GUEST_CARRIER_COOKIE = "matrx_guest_visitor";
+declare function createGuestHandover(options: GuestHandoverOptions): GuestHandover;
+/**
+ * Cookie options for the guest's browser client: its OWN cookie name, never the app singleton's. Pass as
+ * `createBrowserClient(url, key, { isSingleton: false, cookieOptions: guestClientCookieOptions(name) })`.
+ */
+declare function guestClientCookieOptions(cookieName: string, secure?: boolean): {
+    name: string;
+    path: string;
+    sameSite: "lax";
+    secure: boolean;
+    maxAge: number;
+};
+interface GuestSessionAnswer {
+    organizationId: string;
+    adoptedFrom: string | null;
+}
+interface GuestSessionEnsurerOptions {
+    /** The guest browser client's `auth` (its own cookie). */
+    auth: {
+        getSession(): Promise<{
+            data: {
+                session: {
+                    user?: {
+                        id: string;
+                        is_anonymous?: boolean;
+                    };
+                } | null;
+            };
+        }>;
+        setSession(tokens: {
+            access_token: string;
+            refresh_token: string;
+        }): Promise<{
+            error: {
+                message: string;
+            } | null;
+        }>;
+    };
+    /** Workspace (organization) ids the guest belongs to. */
+    listWorkspaceIds(userId: string): Promise<string[]>;
+    /** Base URL of the server that mints guests (`POST <base>/auth/guest/session`). */
+    serverBaseUrl: string | null | undefined;
+    getFingerprint(): Promise<string>;
+    fetch?: typeof fetch;
+    lockName?: string;
+}
+/**
+ * The visitor's guest session, made once. Called on a signed-out visitor's FIRST save or job — never on a
+ * page view. Single flight per tab, and per browser where Web Locks exist (two tabs never mint two guests).
+ */
+declare function createGuestSessionEnsurer(options: GuestSessionEnsurerOptions): () => Promise<GuestSessionAnswer | null>;
+
+export { DEFAULT_GUEST_CARRIER_COOKIE, type GuestClaimOutcome, type GuestCookieJar, type GuestHandover, type GuestHandoverOptions, type GuestPossession, type GuestPromotion, type GuestSessionAnswer, type GuestSessionEnsurerOptions, type GuestStore, type HandoverVia, createGuestHandover, createGuestSessionEnsurer, guestClientCookieOptions, isGuestCookieName, looksLikeVisitorId };