@guard-rail/core 0.3.0 → 0.5.0

package/README.md

@@ -25,14 +25,20 @@ pnpm add @guard-rail/core @supabase/ssr @supabase/supabase-js
 
 Set up the database:
 
-1. Copy `node_modules/@guard-rail/core/supabase/migrations/*.sql` into your own
-   project's `supabase/migrations/`, then run `supabase db push`. No Supabase
-   CLI yet? Paste the file's contents into the SQL editor instead — it runs
-   the same statements, just without the CLI's version tracking.
-2. **Required:** add `guardrail` under **Settings > API > Exposed schemas** in
-   the Supabase dashboard. PostgREST only serves schemas on that list; every
-   table below is otherwise invisible to the client with a "not found in
-   schema cache" error that looks identical to a missing table.
+1. Run `npx guardrail-init-db --push`. It copies the package's migration(s)
+   into your own project's `supabase/migrations/` (skipping any already
+   there — safe to re-run after upgrading), runs `supabase init` if needed,
+   adds `guardrail` to `config.toml`'s exposed schemas for local dev, and
+   applies the migration with `supabase db push`. Leave off `--push` to copy
+   without applying. No Supabase CLI at all? Paste the migration file's
+   contents into the SQL editor instead — same statements, just without the
+   CLI's version tracking.
+2. **Required for a hosted project:** also add `guardrail` under
+   **Settings > API > Exposed schemas** in the Supabase dashboard —
+   `config.toml`'s schemas list only governs local dev. PostgREST only
+   serves schemas on that list; every table below is otherwise invisible to
+   the client with a "not found in schema cache" error that looks identical
+   to a missing table.
 
 Guardrail's tables live in their own `guardrail` Postgres schema, not `public`
 — so a `supabase db reset`, a broad `DROP ... CASCADE`, or a migration tool
@@ -114,7 +120,15 @@ Links take `as="a"` (so `href` type-checks) and edit both the text and the URL:
 ```
 
 To edit, visit any page with `?edit=true`, sign in with a Supabase user, and
-click a field.
+click a field. `?edit=true` itself only grants a short (~10 minute) window to
+reach the sign-in form — a normal visitor never sees any Guardrail chrome, and
+a stray copy of that window (a shared computer, an old tab) self-expires
+rather than showing a sign-in bar indefinitely. It's a dismissable prompt, not
+a standing invitation: a signed-in editor's toolbar isn't on that timer at
+all, and persists for as long as their real session does, with no need to
+revisit `?edit=true` again after the first sign-in. `?edit=false` explicitly
+hides the toolbar (also for ~10 minutes) if you want to preview the site
+without it while still signed in.
 
 ### In Client Components
 
@@ -192,26 +206,42 @@ export default withGuardrail(RootLayout, {
 });
 ```
 
-**Invite emails (Supabase).** Inviting someone creates their account on first
-use and emails them a sign-in link. Three one-time steps in the Supabase
-dashboard, plus one route in your app:
+**Invite emails (Supabase).** Inviting someone emails them a sign-in link
+that creates their account on first use — this works out of the box, no
+route or email template changes needed. A small always-mounted component
+notices the link's tokens (in the URL hash, a `code`, or a `token_hash` —
+whichever style your project's templates happen to produce, including the
+unedited default) and completes the session automatically.
+
+Someone arriving this way has a valid session but no password yet, so they
+get a **Set Password** prompt in place of the usual toolbar — skippable,
+since a magic link works fine on its own indefinitely if they'd rather not.
+The same prompt appears after a password-recovery link.
+
+Two things still worth knowing:
+
+- **Auth → URL Configuration**, in the Supabase dashboard: Site URL and
+  Redirect URLs must actually match wherever your app runs, including in
+  local dev — a mismatch here makes Supabase silently redirect to whatever
+  Site URL *is* configured instead of erroring, which reads exactly like the
+  link "not working" for no visible reason.
+- **Auth → SMTP**: Supabase's built-in mailer allows only a few emails an
+  hour. Configure custom SMTP (Resend, Postmark, SES) before relying on
+  invites. Submitting the same address again re-sends a pending invite.
+
+Prefer a route that verifies server-side rather than relying on client JS to
+notice the redirect? `supabaseConfirmRoute` still works exactly as before —
+mount it and point a custom email template's link at
+`{{ .SiteURL }}/guardrail/confirm?token_hash={{ .TokenHash }}&type=email`:
 
-1. **Route** — `app/guardrail/confirm/route.ts`:
-   ```ts
-   export const GET = supabaseConfirmRoute({ url, anonKey });
-   ```
-2. **Auth → URL Configuration** — set Site URL to your app's origin, and add
-   `<origin>/**` to Redirect URLs.
-3. **Auth → Email Templates** — in both **Confirm signup** and **Magic Link**,
-   point the link at the confirm route using the token hash:
-   ```html
-   <a href="{{ .SiteURL }}/guardrail/confirm?token_hash={{ .TokenHash }}&type=email">Sign in</a>
-   ```
-   The default `{{ .ConfirmationURL }}` uses a PKCE code that only works in
-   the browser that requested it — the admin's, not the invitee's.
-4. **Auth → SMTP** — Supabase's built-in mailer allows only a few emails an
-   hour. Configure custom SMTP (Resend, Postmark, SES) before relying on
-   invites. Submitting the same address again re-sends a pending invite.
+```ts
+// app/guardrail/confirm/route.ts
+export const GET = supabaseConfirmRoute({ url, anonKey });
+```
+
+The default `{{ .ConfirmationURL }}` uses a PKCE code that only works in the
+browser that requested it — the admin's, not the invitee's — so a custom
+template needs the token hash form above either way.
 
 **Bootstrapping.** A site with no members has nobody who can add members, and
 there is deliberately no in-app way to grant yourself a role — that would mean
@@ -434,6 +464,13 @@ const clerkAuth: GRAuthAdapter = {
 };
 ```
 
+`completeAuthRedirect` and `setPassword` are optional too, and go together —
+an adapter with no concept of a redirect-carried session (an OAuth provider
+whose own SDK already handles its callback route, say) omits both, and links
+of that kind pass through untouched. Implement `completeAuthRedirect` to
+support them, returning `needsPassword: true` for a session that has none
+yet; `setPassword` is what the resulting prompt calls.
+
 `getSession()` is the sole authorization check for writes. It must validate the
 session against the provider — never trust the presence of a cookie.
 

package/dist/adapters/supabase/auth.js

@@ -1,4 +1,5 @@
 import { anonClient, assertCredentials, sessionClient } from "./client";
+const NEEDS_PASSWORD_TYPES = /* @__PURE__ */ new Set(["invite", "recovery", "magiclink"]);
 function supabaseAuth(creds) {
   assertCredentials(creds);
   return {
@@ -48,6 +49,55 @@ function supabaseAuth(creds) {
     async logout() {
       const client = await sessionClient(creds);
       await client.auth.signOut();
+    },
+    /**
+     * Whichever of hash/code/tokenHash is present decides the exchange —
+     * these correspond to Supabase's three redirect styles (legacy implicit
+     * grant, PKCE, and the token_hash style Guardrail's own confirm route
+     * already used), so this handles a link regardless of which one a
+     * project's email templates happen to produce, including the
+     * unconfigured default (implicit grant, hash-based — what an unedited
+     * Supabase project actually sends).
+     *
+     * Goes through sessionClient(), the same cookie-writing client
+     * everything else in this adapter uses — setSession/exchangeCodeForSession/
+     * verifyOtp all persist the resulting session through its existing
+     * getAll/setAll bridge, so this needs no browser-side Supabase client of
+     * its own.
+     */
+    async completeAuthRedirect({ hash, code, tokenHash, type }) {
+      const client = await sessionClient(creds);
+      if (hash) {
+        const hashParams = new URLSearchParams(hash);
+        const access_token = hashParams.get("access_token");
+        const refresh_token = hashParams.get("refresh_token");
+        const hashType = hashParams.get("type") ?? type;
+        if (!access_token || !refresh_token) {
+          return { success: false, error: "Redirect link is missing its tokens." };
+        }
+        const { error } = await client.auth.setSession({ access_token, refresh_token });
+        if (error) return { success: false, error: error.message };
+        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(hashType ?? "") };
+      }
+      if (code) {
+        const { error } = await client.auth.exchangeCodeForSession(code);
+        if (error) return { success: false, error: error.message };
+        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type ?? "") };
+      }
+      if (tokenHash && type) {
+        const { error } = await client.auth.verifyOtp({
+          type,
+          token_hash: tokenHash
+        });
+        if (error) return { success: false, error: error.message };
+        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type) };
+      }
+      return { success: false, error: "No redirect data to complete." };
+    },
+    async setPassword(password) {
+      const client = await sessionClient(creds);
+      const { error } = await client.auth.updateUser({ password });
+      return error ? { success: false, error: error.message } : { success: true };
     }
   };
 }

package/dist/adapters/supabase/auth.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/supabase/auth.ts"],"sourcesContent":["import { anonClient, assertCredentials, sessionClient } from \"./client\";\nimport type { SupabaseCredentials } from \"./client\";\nimport type { GRAuthAdapter, GRSession } from \"../../core/adapter-types\";\n\nexport function supabaseAuth(creds: SupabaseCredentials): GRAuthAdapter {\n  assertCredentials(creds);\n\n  return {\n    async authenticate(email, password) {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.signInWithPassword({\n        email,\n        password,\n      });\n\n      if (error) return { success: false, error: error.message };\n      if (!data.user) return { success: false, error: \"User not found.\" };\n\n      return {\n        success: true,\n        session: { userId: data.user.id, email: data.user.email },\n      };\n    },\n\n    /**\n     * Uses getUser(), which revalidates the JWT against the Supabase auth\n     * server. getSession() only decodes the cookie, so it would trust a forged\n     * token.\n     */\n    async getSession(): Promise<GRSession | null> {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.getUser();\n      if (error || !data.user) return null;\n      return { userId: data.user.id, email: data.user.email };\n    },\n\n    /**\n     * Sends a sign-in link that creates the account on first use.\n     *\n     * Requested through the cookie-free client on purpose. A session client\n     * would use PKCE and drop the code verifier into the *admin's* browser,\n     * so the link would fail when the invitee opened it anywhere else. The\n     * email template must point at the confirm route with {{ .TokenHash }},\n     * which verifies server-side and needs no verifier.\n     */\n    async inviteUser(email, options) {\n      const { error } = await anonClient(creds).auth.signInWithOtp({\n        email,\n        options: {\n          shouldCreateUser: true,\n          ...(options?.redirectTo ? { emailRedirectTo: options.redirectTo } : {}),\n        },\n      });\n      return error\n        ? { success: false, error: error.message }\n        : { success: true };\n    },\n\n    async logout() {\n      const client = await sessionClient(creds);\n      await client.auth.signOut();\n    },\n  };\n}\n"],"mappings":"AAAA,SAAS,YAAY,mBAAmB,qBAAqB;AAItD,SAAS,aAAa,OAA2C;AACtE,oBAAkB,KAAK;AAEvB,SAAO;AAAA,IACL,MAAM,aAAa,OAAO,UAAU;AAClC,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK,mBAAmB;AAAA,QAC3D;AAAA,QACA;AAAA,MACF,CAAC;AAED,UAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ;AACzD,UAAI,CAAC,KAAK,KAAM,QAAO,EAAE,SAAS,OAAO,OAAO,kBAAkB;AAElE,aAAO;AAAA,QACL,SAAS;AAAA,QACT,SAAS,EAAE,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,MAAM;AAAA,MAC1D;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,MAAM,aAAwC;AAC5C,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK,QAAQ;AAClD,UAAI,SAAS,CAAC,KAAK,KAAM,QAAO;AAChC,aAAO,EAAE,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,MAAM;AAAA,IACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAWA,MAAM,WAAW,OAAO,SAAS;AAC/B,YAAM,EAAE,MAAM,IAAI,MAAM,WAAW,KAAK,EAAE,KAAK,cAAc;AAAA,QAC3D;AAAA,QACA,SAAS;AAAA,UACP,kBAAkB;AAAA,UAClB,GAAI,SAAS,aAAa,EAAE,iBAAiB,QAAQ,WAAW,IAAI,CAAC;AAAA,QACvE;AAAA,MACF,CAAC;AACD,aAAO,QACH,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ,IACvC,EAAE,SAAS,KAAK;AAAA,IACtB;AAAA,IAEA,MAAM,SAAS;AACb,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,OAAO,KAAK,QAAQ;AAAA,IAC5B;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../../src/adapters/supabase/auth.ts"],"sourcesContent":["import type { EmailOtpType } from \"@supabase/supabase-js\";\nimport { anonClient, assertCredentials, sessionClient } from \"./client\";\nimport type { SupabaseCredentials } from \"./client\";\nimport type {\n  AuthRedirectParams,\n  GRAuthAdapter,\n  GRSession,\n} from \"../../core/adapter-types\";\n\n// \"invite\" covers Supabase's own admin-API invite flow; \"recovery\" is\n// forgot-password. \"magiclink\" belongs here too — deliberately, not an\n// oversight — because inviteUser() below sends one (see its own comment for\n// why) rather than an \"invite\"-typed email, so this is the type Guardrail's\n// actual, real invite flow produces. A returning magic-link user who already\n// has a password sees this redundantly, but it's skippable, and the\n// alternative — never prompting the person this feature exists for — isn't\n// an acceptable trade to avoid that.\nconst NEEDS_PASSWORD_TYPES = new Set([\"invite\", \"recovery\", \"magiclink\"]);\n\nexport function supabaseAuth(creds: SupabaseCredentials): GRAuthAdapter {\n  assertCredentials(creds);\n\n  return {\n    async authenticate(email, password) {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.signInWithPassword({\n        email,\n        password,\n      });\n\n      if (error) return { success: false, error: error.message };\n      if (!data.user) return { success: false, error: \"User not found.\" };\n\n      return {\n        success: true,\n        session: { userId: data.user.id, email: data.user.email },\n      };\n    },\n\n    /**\n     * Uses getUser(), which revalidates the JWT against the Supabase auth\n     * server. getSession() only decodes the cookie, so it would trust a forged\n     * token.\n     */\n    async getSession(): Promise<GRSession | null> {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.getUser();\n      if (error || !data.user) return null;\n      return { userId: data.user.id, email: data.user.email };\n    },\n\n    /**\n     * Sends a sign-in link that creates the account on first use.\n     *\n     * Requested through the cookie-free client on purpose. A session client\n     * would use PKCE and drop the code verifier into the *admin's* browser,\n     * so the link would fail when the invitee opened it anywhere else. The\n     * email template must point at the confirm route with {{ .TokenHash }},\n     * which verifies server-side and needs no verifier.\n     */\n    async inviteUser(email, options) {\n      const { error } = await anonClient(creds).auth.signInWithOtp({\n        email,\n        options: {\n          shouldCreateUser: true,\n          ...(options?.redirectTo ? { emailRedirectTo: options.redirectTo } : {}),\n        },\n      });\n      return error\n        ? { success: false, error: error.message }\n        : { success: true };\n    },\n\n    async logout() {\n      const client = await sessionClient(creds);\n      await client.auth.signOut();\n    },\n\n    /**\n     * Whichever of hash/code/tokenHash is present decides the exchange —\n     * these correspond to Supabase's three redirect styles (legacy implicit\n     * grant, PKCE, and the token_hash style Guardrail's own confirm route\n     * already used), so this handles a link regardless of which one a\n     * project's email templates happen to produce, including the\n     * unconfigured default (implicit grant, hash-based — what an unedited\n     * Supabase project actually sends).\n     *\n     * Goes through sessionClient(), the same cookie-writing client\n     * everything else in this adapter uses — setSession/exchangeCodeForSession/\n     * verifyOtp all persist the resulting session through its existing\n     * getAll/setAll bridge, so this needs no browser-side Supabase client of\n     * its own.\n     */\n    async completeAuthRedirect({ hash, code, tokenHash, type }: AuthRedirectParams) {\n      const client = await sessionClient(creds);\n\n      if (hash) {\n        const hashParams = new URLSearchParams(hash);\n        const access_token = hashParams.get(\"access_token\");\n        const refresh_token = hashParams.get(\"refresh_token\");\n        const hashType = hashParams.get(\"type\") ?? type;\n        if (!access_token || !refresh_token) {\n          return { success: false, error: \"Redirect link is missing its tokens.\" };\n        }\n        const { error } = await client.auth.setSession({ access_token, refresh_token });\n        if (error) return { success: false, error: error.message };\n        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(hashType ?? \"\") };\n      }\n\n      if (code) {\n        const { error } = await client.auth.exchangeCodeForSession(code);\n        if (error) return { success: false, error: error.message };\n        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type ?? \"\") };\n      }\n\n      if (tokenHash && type) {\n        const { error } = await client.auth.verifyOtp({\n          type: type as EmailOtpType,\n          token_hash: tokenHash,\n        });\n        if (error) return { success: false, error: error.message };\n        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type) };\n      }\n\n      return { success: false, error: \"No redirect data to complete.\" };\n    },\n\n    async setPassword(password: string) {\n      const client = await sessionClient(creds);\n      const { error } = await client.auth.updateUser({ password });\n      return error ? { success: false, error: error.message } : { success: true };\n    },\n  };\n}\n"],"mappings":"AACA,SAAS,YAAY,mBAAmB,qBAAqB;AAgB7D,MAAM,uBAAuB,oBAAI,IAAI,CAAC,UAAU,YAAY,WAAW,CAAC;AAEjE,SAAS,aAAa,OAA2C;AACtE,oBAAkB,KAAK;AAEvB,SAAO;AAAA,IACL,MAAM,aAAa,OAAO,UAAU;AAClC,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK,mBAAmB;AAAA,QAC3D;AAAA,QACA;AAAA,MACF,CAAC;AAED,UAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ;AACzD,UAAI,CAAC,KAAK,KAAM,QAAO,EAAE,SAAS,OAAO,OAAO,kBAAkB;AAElE,aAAO;AAAA,QACL,SAAS;AAAA,QACT,SAAS,EAAE,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,MAAM;AAAA,MAC1D;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,MAAM,aAAwC;AAC5C,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK,QAAQ;AAClD,UAAI,SAAS,CAAC,KAAK,KAAM,QAAO;AAChC,aAAO,EAAE,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,MAAM;AAAA,IACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAWA,MAAM,WAAW,OAAO,SAAS;AAC/B,YAAM,EAAE,MAAM,IAAI,MAAM,WAAW,KAAK,EAAE,KAAK,cAAc;AAAA,QAC3D;AAAA,QACA,SAAS;AAAA,UACP,kBAAkB;AAAA,UAClB,GAAI,SAAS,aAAa,EAAE,iBAAiB,QAAQ,WAAW,IAAI,CAAC;AAAA,QACvE;AAAA,MACF,CAAC;AACD,aAAO,QACH,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ,IACvC,EAAE,SAAS,KAAK;AAAA,IACtB;AAAA,IAEA,MAAM,SAAS;AACb,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,OAAO,KAAK,QAAQ;AAAA,IAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAiBA,MAAM,qBAAqB,EAAE,MAAM,MAAM,WAAW,KAAK,GAAuB;AAC9E,YAAM,SAAS,MAAM,cAAc,KAAK;AAExC,UAAI,MAAM;AACR,cAAM,aAAa,IAAI,gBAAgB,IAAI;AAC3C,cAAM,eAAe,WAAW,IAAI,cAAc;AAClD,cAAM,gBAAgB,WAAW,IAAI,eAAe;AACpD,cAAM,WAAW,WAAW,IAAI,MAAM,KAAK;AAC3C,YAAI,CAAC,gBAAgB,CAAC,eAAe;AACnC,iBAAO,EAAE,SAAS,OAAO,OAAO,uCAAuC;AAAA,QACzE;AACA,cAAM,EAAE,MAAM,IAAI,MAAM,OAAO,KAAK,WAAW,EAAE,cAAc,cAAc,CAAC;AAC9E,YAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ;AACzD,eAAO,EAAE,SAAS,MAAM,eAAe,qBAAqB,IAAI,YAAY,EAAE,EAAE;AAAA,MAClF;AAEA,UAAI,MAAM;AACR,cAAM,EAAE,MAAM,IAAI,MAAM,OAAO,KAAK,uBAAuB,IAAI;AAC/D,YAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ;AACzD,eAAO,EAAE,SAAS,MAAM,eAAe,qBAAqB,IAAI,QAAQ,EAAE,EAAE;AAAA,MAC9E;AAEA,UAAI,aAAa,MAAM;AACrB,cAAM,EAAE,MAAM,IAAI,MAAM,OAAO,KAAK,UAAU;AAAA,UAC5C;AAAA,UACA,YAAY;AAAA,QACd,CAAC;AACD,YAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ;AACzD,eAAO,EAAE,SAAS,MAAM,eAAe,qBAAqB,IAAI,IAAI,EAAE;AAAA,MACxE;AAEA,aAAO,EAAE,SAAS,OAAO,OAAO,gCAAgC;AAAA,IAClE;AAAA,IAEA,MAAM,YAAY,UAAkB;AAClC,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,IAAI,MAAM,OAAO,KAAK,WAAW,EAAE,SAAS,CAAC;AAC3D,aAAO,QAAQ,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ,IAAI,EAAE,SAAS,KAAK;AAAA,IAC5E;AAAA,EACF;AACF;","names":[]}

package/dist/cli/init-db.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/init-db.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function commandExists(cmd) {
+  const res = process.platform === "win32" ? spawnSync("where", [cmd]) : spawnSync("which", [cmd]);
+  return res.status === 0;
+}
+function run(cmd, args) {
+  const res = spawnSync(cmd, args, { stdio: "inherit" });
+  if (res.status !== 0) {
+    throw new Error(`${cmd} ${args.join(" ")} exited with code ${res.status}`);
+  }
+}
+function fail(message) {
+  console.error(`
+${message}
+`);
+  process.exit(1);
+}
+const USAGE = `Usage:
+  guardrail-init-db [--push]
+
+Copies Guardrail's migration(s) from this package into ./supabase/migrations/
+(skipping any already present there), runs \`supabase init\` if this project
+has no supabase/config.toml yet, and adds "guardrail" to its exposed schemas
+for local dev.
+
+--push  Also run \`supabase db push\` once the files are in place. Without it,
+        the migration is copied but not applied \u2014 run \`supabase db push\`
+        yourself (after \`supabase link\`, if this project isn't linked yet).`;
+function patchExposedSchemas(configPath) {
+  const content = readFileSync(configPath, "utf8");
+  const patched = content.replace(
+    /(\[api\][\s\S]*?schemas\s*=\s*\[)([^\]]*)(\])/,
+    (match, pre, inner, post) => {
+      if (inner.includes('"guardrail"')) return match;
+      const trimmed = inner.trimEnd();
+      const sep = trimmed === "" || trimmed.endsWith(",") ? " " : ", ";
+      return `${pre}${inner}${sep}"guardrail"${post}`;
+    }
+  );
+  if (patched === content && !content.includes('"guardrail"')) {
+    console.warn(
+      'Could not find the [api] schemas setting in supabase/config.toml to patch automatically \u2014 add "guardrail" to it yourself before `supabase start`.'
+    );
+    return;
+  }
+  writeFileSync(configPath, patched);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(USAGE);
+    return;
+  }
+  const push = args.includes("--push");
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.join(__dirname, "..", "..");
+  const srcDir = path.join(pkgRoot, "supabase", "migrations");
+  if (!existsSync(srcDir)) {
+    fail(`No bundled migrations found at ${srcDir} \u2014 is @guard-rail/core installed correctly?`);
+  }
+  const destDir = path.join(process.cwd(), "supabase", "migrations");
+  mkdirSync(destDir, { recursive: true });
+  const existing = new Set(readdirSync(destDir));
+  const copied = [];
+  for (const file of readdirSync(srcDir)) {
+    if (existing.has(file)) continue;
+    copyFileSync(path.join(srcDir, file), path.join(destDir, file));
+    copied.push(file);
+  }
+  if (copied.length === 0) {
+    console.log("supabase/migrations/ is already up to date \u2014 nothing to copy.");
+  } else {
+    console.log(`Copied ${copied.length} migration${copied.length === 1 ? "" : "s"}:`);
+    for (const file of copied) console.log(`  supabase/migrations/${file}`);
+  }
+  if (!commandExists("supabase")) {
+    console.log(
+      "\nSupabase CLI not found \u2014 apply the migration yourself (paste it into the SQL editor, or install the CLI and run `supabase db push`)."
+    );
+    return;
+  }
+  const configPath = path.join(process.cwd(), "supabase", "config.toml");
+  if (!existsSync(configPath)) {
+    try {
+      run("supabase", ["init"]);
+    } catch {
+      console.warn("\n`supabase init` failed \u2014 you can run it yourself.");
+      return;
+    }
+  }
+  if (existsSync(configPath)) patchExposedSchemas(configPath);
+  if (!push) {
+    console.log(
+      "\nRun `guardrail-init-db --push` (or `supabase db push` yourself) to apply it."
+    );
+    return;
+  }
+  try {
+    run("supabase", ["db", "push"]);
+  } catch {
+    console.warn(
+      "\n`supabase db push` failed \u2014 if this project isn't linked yet, run `supabase link` first, then `supabase db push`."
+    );
+  }
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=init-db.js.map

package/dist/cli/init-db.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/init-db.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * Copies Guardrail's SQL migration(s) into the current project's own\n * supabase/migrations/, then (optionally) applies them — the step\n * create-guardrail already automates for a brand-new scaffold (see\n * copyMigration()/maybeLinkAndPush() in that package), but has no\n * equivalent for an existing Next.js + Supabase app that just ran\n * `npm install @guard-rail/core`. Until now, postinstall.mjs pointed at\n * doing this by hand: \"Copy\n * node_modules/@guard-rail/core/supabase/migrations/*.sql into your own\n * supabase/migrations/, then `supabase db push`.\"\n *\n * Copies by filename, skipping anything already present in the destination\n * — safe to re-run after upgrading the package: it only ever adds\n * migrations this version ships that a prior run didn't already copy, and\n * never overwrites one that's already there.\n *\n * Deliberately non-interactive (flags only, no prompts), unlike\n * create-guardrail's wizard-style prompts — this is meant to be a single\n * command a developer (or a script) runs once against a project that\n * already exists, not a guided setup flow.\n */\nimport { spawnSync } from \"node:child_process\";\nimport {\n  existsSync,\n  mkdirSync,\n  copyFileSync,\n  readdirSync,\n  readFileSync,\n  writeFileSync,\n} from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nfunction commandExists(cmd: string): boolean {\n  // See create-guardrail's util.ts for why `which`/`where` over `command -v`\n  // with shell:true — no shell needed, no Node deprecation warning.\n  const res =\n    process.platform === \"win32\" ? spawnSync(\"where\", [cmd]) : spawnSync(\"which\", [cmd]);\n  return res.status === 0;\n}\n\n/** Throws with the failing command's name — every call site decides whether that's fatal. */\nfunction run(cmd: string, args: string[]): void {\n  const res = spawnSync(cmd, args, { stdio: \"inherit\" });\n  if (res.status !== 0) {\n    throw new Error(`${cmd} ${args.join(\" \")} exited with code ${res.status}`);\n  }\n}\n\nfunction fail(message: string): never {\n  console.error(`\\n${message}\\n`);\n  process.exit(1);\n}\n\nconst USAGE = `Usage:\n  guardrail-init-db [--push]\n\nCopies Guardrail's migration(s) from this package into ./supabase/migrations/\n(skipping any already present there), runs \\`supabase init\\` if this project\nhas no supabase/config.toml yet, and adds \"guardrail\" to its exposed schemas\nfor local dev.\n\n--push  Also run \\`supabase db push\\` once the files are in place. Without it,\n        the migration is copied but not applied — run \\`supabase db push\\`\n        yourself (after \\`supabase link\\`, if this project isn't linked yet).`;\n\n/**\n * Idempotent by design (a no-op if \"guardrail\" is already listed) — safe to\n * run on every invocation rather than only the first, including against a\n * config.toml a developer has since hand-edited.\n */\nfunction patchExposedSchemas(configPath: string): void {\n  const content = readFileSync(configPath, \"utf8\");\n  const patched = content.replace(\n    /(\\[api\\][\\s\\S]*?schemas\\s*=\\s*\\[)([^\\]]*)(\\])/,\n    (match, pre: string, inner: string, post: string) => {\n      if (inner.includes('\"guardrail\"')) return match;\n      const trimmed = inner.trimEnd();\n      const sep = trimmed === \"\" || trimmed.endsWith(\",\") ? \" \" : \", \";\n      return `${pre}${inner}${sep}\"guardrail\"${post}`;\n    },\n  );\n\n  if (patched === content && !content.includes('\"guardrail\"')) {\n    console.warn(\n      'Could not find the [api] schemas setting in supabase/config.toml to patch ' +\n        'automatically — add \"guardrail\" to it yourself before `supabase start`.',\n    );\n    return;\n  }\n  writeFileSync(configPath, patched);\n}\n\nasync function main() {\n  const args = process.argv.slice(2);\n  if (args.includes(\"--help\") || args.includes(\"-h\")) {\n    console.log(USAGE);\n    return;\n  }\n  const push = args.includes(\"--push\");\n\n  // This file's own location, not the invoking project's node_modules —\n  // resolves the migrations this installed package version ships,\n  // regardless of how the command was invoked (npx, a package.json script,\n  // a workspace link).\n  const __dirname = path.dirname(fileURLToPath(import.meta.url));\n  const pkgRoot = path.join(__dirname, \"..\", \"..\");\n  const srcDir = path.join(pkgRoot, \"supabase\", \"migrations\");\n  if (!existsSync(srcDir)) {\n    fail(`No bundled migrations found at ${srcDir} — is @guard-rail/core installed correctly?`);\n  }\n\n  const destDir = path.join(process.cwd(), \"supabase\", \"migrations\");\n  mkdirSync(destDir, { recursive: true });\n  const existing = new Set(readdirSync(destDir));\n\n  const copied: string[] = [];\n  for (const file of readdirSync(srcDir)) {\n    if (existing.has(file)) continue;\n    copyFileSync(path.join(srcDir, file), path.join(destDir, file));\n    copied.push(file);\n  }\n\n  if (copied.length === 0) {\n    console.log(\"supabase/migrations/ is already up to date — nothing to copy.\");\n  } else {\n    console.log(`Copied ${copied.length} migration${copied.length === 1 ? \"\" : \"s\"}:`);\n    for (const file of copied) console.log(`  supabase/migrations/${file}`);\n  }\n\n  if (!commandExists(\"supabase\")) {\n    console.log(\n      \"\\nSupabase CLI not found — apply the migration yourself (paste it into the SQL \" +\n        \"editor, or install the CLI and run `supabase db push`).\",\n    );\n    return;\n  }\n\n  const configPath = path.join(process.cwd(), \"supabase\", \"config.toml\");\n  if (!existsSync(configPath)) {\n    try {\n      run(\"supabase\", [\"init\"]);\n    } catch {\n      console.warn(\"\\n`supabase init` failed — you can run it yourself.\");\n      return;\n    }\n  }\n  if (existsSync(configPath)) patchExposedSchemas(configPath);\n\n  if (!push) {\n    console.log(\n      \"\\nRun `guardrail-init-db --push` (or `supabase db push` yourself) to apply it.\",\n    );\n    return;\n  }\n\n  try {\n    run(\"supabase\", [\"db\", \"push\"]);\n  } catch {\n    console.warn(\n      \"\\n`supabase db push` failed — if this project isn't linked yet, run `supabase \" +\n        \"link` first, then `supabase db push`.\",\n    );\n  }\n}\n\nmain().catch((err) => {\n  console.error(err);\n  process.exit(1);\n});\n"],"mappings":"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","names":[]}

package/dist/core/adapter-types.d.ts

@@ -97,6 +97,48 @@ interface GRAuthAdapter {
      */
     getSession: () => Promise<GRSession | null>;
     logout: () => Promise<void>;
+    /**
+     * Completes a session that arrived via a redirect link — an invite, magic
+     * link, or password-recovery email — rather than the normal sign-in form.
+     * Optional: an adapter with no such concept (an OAuth provider whose own
+     * SDK already handles its callback route, say) simply omits it, and links
+     * of this kind pass through Guardrail untouched.
+     *
+     * Whatever the client found in the URL is handed through as-is — which of
+     * `hash`/`code`/`tokenHash` is present depends on the provider's own
+     * redirect style, not a choice Guardrail's core makes. `needsPassword` in
+     * the result tells the caller to prompt for one: an invited or
+     * password-recovering person has a valid session but no password yet.
+     */
+    completeAuthRedirect?: (params: AuthRedirectParams) => Promise<{
+        success: boolean;
+        needsPassword?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Sets the current session's password — the other half of
+     * `completeAuthRedirect`'s `needsPassword`. Optional for the same reason
+     * `authenticate` is: only meaningful for a password-based adapter.
+     */
+    setPassword?: (password: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Raw redirect data as the browser found it — see completeAuthRedirect.
+ * Hash-based tokens never reach the server on their own; the browser has to
+ * read them and hand them here.
+ */
+interface AuthRedirectParams {
+    /** window.location.hash, minus its leading '#' (the implicit-grant style). */
+    hash?: string;
+    /** The `code` query param (the PKCE style). */
+    code?: string;
+    /** The `token_hash` query param (Guardrail's own documented confirm-route style, detected here too so that route stays opt-in rather than required). */
+    tokenHash?: string;
+    /** Accompanies `code` or `tokenHash` — e.g. "invite", "recovery", "magiclink". */
+    type?: string;
 }
 type AuthResult = {
     success: true;
@@ -243,4 +285,4 @@ interface GRConfig {
     prefetch?: false | GRPrefetch;
 }
 
-export type { AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget };
+export type { AuthRedirectParams, AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget };

package/dist/core/defs.d.ts

@@ -1,7 +1,48 @@
 declare const GR_COOKIES: {
-    /** Signals intent to edit. Not a credential — carries no authority on its own. */
+    /**
+     * Signals intent to edit. Carries no authority on its own — every write
+     * still goes through a real, server-verified role check, independent of
+     * this — but it does decide whether the admin chrome (the sign-in bar, or
+     * the toolbar) renders at all, so it is not harmless either: a stale copy
+     * of it is a real, if low-stakes, exposure ("there's a CMS here") to
+     * whoever's browser it's sitting in next, not just its original visitor.
+     *
+     * Values: "true" (show chrome — the short-lived grace window below, for
+     * someone not yet authenticated to reach the sign-in form), "false"
+     * (explicitly suppressed, e.g. ?edit=false previewing without chrome while
+     * still signed in), or absent. Absent defers entirely to whether a real
+     * session exists (see withGuardrail) — an authenticated editor's chrome
+     * persists for as long as their actual session does, with no separate
+     * timer of its own to fall out of sync with it.
+     */
     readonly EDIT_MODE: "gr_edit_mode";
+    /**
+     * Set server-side the moment a redirect-carried session (an invite or
+     * password-recovery link) completes, so the next render — which has no
+     * other way to know that just happened — prompts to set a password
+     * instead of showing the normal toolbar. Cleared once they do, or once
+     * they explicitly skip.
+     */
+    readonly NEEDS_PASSWORD: "gr_needs_password";
 };
+/**
+ * How long the edit-mode cookie's "true"/"false" values last before
+ * reverting to the session-derived default. Short on purpose: it only ever
+ * needs to outlive the handful of clicks between landing on ?edit=true and
+ * actually typing a password (or, for ?edit=false, a quick chrome-free
+ * preview) — not a whole working session, which persists through real auth
+ * instead. Bounds how long a stray copy of this cookie can show anything to
+ * whoever's browser it's left in, self-healing without needing an explicit
+ * logout.
+ */
+declare const GR_EDIT_MODE_TTL_SECONDS: number;
+/**
+ * How long the set-a-password prompt stays up after an invite/recovery link
+ * completes. Longer than the edit-mode window above — picking a password
+ * takes more than one click — but still bounded, rather than nagging
+ * indefinitely if it's skipped and the cookie is somehow never cleared.
+ */
+declare const GR_NEEDS_PASSWORD_TTL_SECONDS: number;
 /**
  * Dedicated Postgres schema, not `public`. A name prefix alone only guards
  * against accidental collisions; it does nothing against a `supabase db
@@ -19,4 +60,4 @@ declare const GR_TABLE = "gr_content";
 declare const GR_MEMBERS_TABLE = "gr_members";
 declare const GR_REPEATER_TABLE = "gr_repeater_items";
 
-export { GR_COOKIES, GR_MEMBERS_TABLE, GR_REPEATER_TABLE, GR_SCHEMA, GR_TABLE };
+export { GR_COOKIES, GR_EDIT_MODE_TTL_SECONDS, GR_MEMBERS_TABLE, GR_NEEDS_PASSWORD_TTL_SECONDS, GR_REPEATER_TABLE, GR_SCHEMA, GR_TABLE };

package/dist/core/defs.js

@@ -1,14 +1,41 @@
 const GR_COOKIES = {
-  /** Signals intent to edit. Not a credential — carries no authority on its own. */
-  EDIT_MODE: "gr_edit_mode"
+  /**
+   * Signals intent to edit. Carries no authority on its own — every write
+   * still goes through a real, server-verified role check, independent of
+   * this — but it does decide whether the admin chrome (the sign-in bar, or
+   * the toolbar) renders at all, so it is not harmless either: a stale copy
+   * of it is a real, if low-stakes, exposure ("there's a CMS here") to
+   * whoever's browser it's sitting in next, not just its original visitor.
+   *
+   * Values: "true" (show chrome — the short-lived grace window below, for
+   * someone not yet authenticated to reach the sign-in form), "false"
+   * (explicitly suppressed, e.g. ?edit=false previewing without chrome while
+   * still signed in), or absent. Absent defers entirely to whether a real
+   * session exists (see withGuardrail) — an authenticated editor's chrome
+   * persists for as long as their actual session does, with no separate
+   * timer of its own to fall out of sync with it.
+   */
+  EDIT_MODE: "gr_edit_mode",
+  /**
+   * Set server-side the moment a redirect-carried session (an invite or
+   * password-recovery link) completes, so the next render — which has no
+   * other way to know that just happened — prompts to set a password
+   * instead of showing the normal toolbar. Cleared once they do, or once
+   * they explicitly skip.
+   */
+  NEEDS_PASSWORD: "gr_needs_password"
 };
+const GR_EDIT_MODE_TTL_SECONDS = 10 * 60;
+const GR_NEEDS_PASSWORD_TTL_SECONDS = 30 * 60;
 const GR_SCHEMA = "guardrail";
 const GR_TABLE = "gr_content";
 const GR_MEMBERS_TABLE = "gr_members";
 const GR_REPEATER_TABLE = "gr_repeater_items";
 export {
   GR_COOKIES,
+  GR_EDIT_MODE_TTL_SECONDS,
   GR_MEMBERS_TABLE,
+  GR_NEEDS_PASSWORD_TTL_SECONDS,
   GR_REPEATER_TABLE,
   GR_SCHEMA,
   GR_TABLE

package/dist/core/defs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/core/defs.ts"],"sourcesContent":["export const GR_COOKIES = {\n  /** Signals intent to edit. Not a credential — carries no authority on its own. */\n  EDIT_MODE: \"gr_edit_mode\",\n} as const;\n\n/**\n * Dedicated Postgres schema, not `public`. A name prefix alone only guards\n * against accidental collisions; it does nothing against a `supabase db\n * reset`, a broad `DROP ... CASCADE`, or a migration tool that diffs and\n * \"reconciles\" everything in `public` as if it owns that namespace. A\n * separate schema keeps Guardrail's tables outside that blast radius —\n * the same reason auth.* and storage.* are their own schemas, not public.*.\n *\n * Requires \"guardrail\" to be added under Settings > API > Exposed schemas in\n * the Supabase dashboard — PostgREST only serves schemas on that list, and no\n * migration can add itself to it.\n */\nexport const GR_SCHEMA = \"guardrail\";\n\nexport const GR_TABLE = \"gr_content\";\nexport const GR_MEMBERS_TABLE = \"gr_members\";\nexport const GR_REPEATER_TABLE = \"gr_repeater_items\";\n"],"mappings":"AAAO,MAAM,aAAa;AAAA;AAAA,EAExB,WAAW;AACb;AAcO,MAAM,YAAY;AAElB,MAAM,WAAW;AACjB,MAAM,mBAAmB;AACzB,MAAM,oBAAoB;","names":[]}
+{"version":3,"sources":["../../src/core/defs.ts"],"sourcesContent":["export const GR_COOKIES = {\n  /**\n   * Signals intent to edit. Carries no authority on its own — every write\n   * still goes through a real, server-verified role check, independent of\n   * this — but it does decide whether the admin chrome (the sign-in bar, or\n   * the toolbar) renders at all, so it is not harmless either: a stale copy\n   * of it is a real, if low-stakes, exposure (\"there's a CMS here\") to\n   * whoever's browser it's sitting in next, not just its original visitor.\n   *\n   * Values: \"true\" (show chrome — the short-lived grace window below, for\n   * someone not yet authenticated to reach the sign-in form), \"false\"\n   * (explicitly suppressed, e.g. ?edit=false previewing without chrome while\n   * still signed in), or absent. Absent defers entirely to whether a real\n   * session exists (see withGuardrail) — an authenticated editor's chrome\n   * persists for as long as their actual session does, with no separate\n   * timer of its own to fall out of sync with it.\n   */\n  EDIT_MODE: \"gr_edit_mode\",\n  /**\n   * Set server-side the moment a redirect-carried session (an invite or\n   * password-recovery link) completes, so the next render — which has no\n   * other way to know that just happened — prompts to set a password\n   * instead of showing the normal toolbar. Cleared once they do, or once\n   * they explicitly skip.\n   */\n  NEEDS_PASSWORD: \"gr_needs_password\",\n} as const;\n\n/**\n * How long the edit-mode cookie's \"true\"/\"false\" values last before\n * reverting to the session-derived default. Short on purpose: it only ever\n * needs to outlive the handful of clicks between landing on ?edit=true and\n * actually typing a password (or, for ?edit=false, a quick chrome-free\n * preview) — not a whole working session, which persists through real auth\n * instead. Bounds how long a stray copy of this cookie can show anything to\n * whoever's browser it's left in, self-healing without needing an explicit\n * logout.\n */\nexport const GR_EDIT_MODE_TTL_SECONDS = 10 * 60;\n\n/**\n * How long the set-a-password prompt stays up after an invite/recovery link\n * completes. Longer than the edit-mode window above — picking a password\n * takes more than one click — but still bounded, rather than nagging\n * indefinitely if it's skipped and the cookie is somehow never cleared.\n */\nexport const GR_NEEDS_PASSWORD_TTL_SECONDS = 30 * 60;\n\n/**\n * Dedicated Postgres schema, not `public`. A name prefix alone only guards\n * against accidental collisions; it does nothing against a `supabase db\n * reset`, a broad `DROP ... CASCADE`, or a migration tool that diffs and\n * \"reconciles\" everything in `public` as if it owns that namespace. A\n * separate schema keeps Guardrail's tables outside that blast radius —\n * the same reason auth.* and storage.* are their own schemas, not public.*.\n *\n * Requires \"guardrail\" to be added under Settings > API > Exposed schemas in\n * the Supabase dashboard — PostgREST only serves schemas on that list, and no\n * migration can add itself to it.\n */\nexport const GR_SCHEMA = \"guardrail\";\n\nexport const GR_TABLE = \"gr_content\";\nexport const GR_MEMBERS_TABLE = \"gr_members\";\nexport const GR_REPEATER_TABLE = \"gr_repeater_items\";\n"],"mappings":"AAAO,MAAM,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBxB,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQX,gBAAgB;AAClB;AAYO,MAAM,2BAA2B,KAAK;AAQtC,MAAM,gCAAgC,KAAK;AAc3C,MAAM,YAAY;AAElB,MAAM,WAAW;AACjB,MAAM,mBAAmB;AACzB,MAAM,oBAAoB;","names":[]}

package/dist/core/types.d.ts

@@ -113,6 +113,9 @@ interface GRAuthCapabilities {
 interface GRState {
     isAuth: boolean;
     isEditMode: boolean;
+    /** A redirect-carried session (an invite or recovery link) just completed
+     * and has no password yet — see completeAuthRedirect. */
+    needsPassword: boolean;
     siteId: string;
     /** Null when the signed-in user holds no role on this site. */
     role: GRRole | null;
@@ -145,5 +148,9 @@ type ActionState = {
     email?: string;
     password?: string;
 };
+type SetPasswordState = {
+    success?: boolean;
+    error?: string;
+};
 
-export type { ActionState, GRAsset, GRAuthCapabilities, GRContent, GRMember, GRRepeaterItem, GRRole, GRState, GRViewer, HTMLKeys, NextImageExtras, OverrideRow, OverrideType, OverrideValue, PolymorphicProps };
+export type { ActionState, GRAsset, GRAuthCapabilities, GRContent, GRMember, GRRepeaterItem, GRRole, GRState, GRViewer, HTMLKeys, NextImageExtras, OverrideRow, OverrideType, OverrideValue, PolymorphicProps, SetPasswordState };

package/dist/index.client.d.ts

@@ -1,10 +1,10 @@
 export { GRail } from './react/GRail/universal.js';
 export { useGRail } from './react/Provider.js';
-export { createAssetUpload, inviteMember, listAssets, listTeam, removeMember, updateMemberRole } from './server/actions.js';
+export { createAssetUpload, inviteMember, listAssets, listTeam, removeMember, setPasswordAction, skipSetPasswordAction, updateMemberRole } from './server/actions.js';
 export { addRepeaterItem, removeRepeaterItem, reorderRepeaterItems } from './server/repeaterActions.js';
 export { GRepeaterProps, RepeaterItemProps } from './react/Repeater/index.js';
-export { GRAsset, GRMember, GRRepeaterItem, GRRole, GRState, GRViewer, HTMLKeys, OverrideRow, OverrideType, OverrideValue, PolymorphicProps } from './core/types.js';
-export { AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget } from './core/adapter-types.js';
+export { ActionState, GRAsset, GRMember, GRRepeaterItem, GRRole, GRState, GRViewer, HTMLKeys, OverrideRow, OverrideType, OverrideValue, PolymorphicProps, SetPasswordState } from './core/types.js';
+export { AuthRedirectParams, AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget } from './core/adapter-types.js';
 import 'react/jsx-runtime';
 import 'react';
 

package/dist/index.client.js

@@ -6,7 +6,9 @@ import {
   updateMemberRole,
   removeMember,
   createAssetUpload,
-  listAssets
+  listAssets,
+  setPasswordAction,
+  skipSetPasswordAction
 } from "./server/actions";
 import {
   addRepeaterItem,
@@ -59,6 +61,8 @@ export {
   removeMember,
   removeRepeaterItem,
   reorderRepeaterItems,
+  setPasswordAction,
+  skipSetPasswordAction,
   updateMemberRole,
   useGRail,
   withGuardrail

package/dist/index.client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.client.ts"],"sourcesContent":["// Client-graph entry. `import ... from \"@guard-rail/core\"` resolves here from a\n// Client Component (see \"exports\" in package.json) and to ./index from a\n// Server Component, so an app uses one import path everywhere.\n//\n// Nothing server-only may be imported here — this is bundled for the browser.\n// Server Actions are fine: a \"use server\" module is replaced by references in\n// the client bundle, which is what lets an app build its own team/repeater UI\n// in a Client Component.\n\nexport { GRail } from \"./react/GRail/universal\";\nexport { useGRail } from \"./react/Provider\";\n\nexport {\n  listTeam,\n  inviteMember,\n  updateMemberRole,\n  removeMember,\n  createAssetUpload,\n  listAssets,\n} from \"./server/actions\";\nexport {\n  addRepeaterItem,\n  removeRepeaterItem,\n  reorderRepeaterItems,\n} from \"./server/repeaterActions\";\n\n/**\n * Stand-ins for the server-only exports, so importing one from a Client\n * Component fails with an explanation instead of an undefined-is-not-a-function\n * deep in a render. Also what a tool that doesn't set the \"react-server\"\n * condition (a test runner, a plain Node script) gets from the package root —\n * `@guard-rail/core/server` is the explicit path to the real ones there.\n */\nfunction serverOnly(name: string, hint: string) {\n  return (..._args: unknown[]): never => {\n    throw new Error(\n      `Guardrail: ${name} only works in a Server Component. ${hint} ` +\n        `(If this isn't a Client Component, your tooling may not set the ` +\n        `\"react-server\" condition — import from \"@guard-rail/core/server\" instead.)`,\n    );\n  };\n}\n\nexport const withGuardrail = serverOnly(\n  \"withGuardrail()\",\n  \"Call it in your root layout, which is a Server Component.\",\n);\nexport const configureGuardrail = serverOnly(\n  \"configureGuardrail()\",\n  \"Configuration is applied by withGuardrail() in your root layout.\",\n);\nexport const GRepeater = serverOnly(\n  \"<GRepeater>\",\n  \"Render it in a Server Component and pass it into this one as children or a prop.\",\n);\nexport const listRepeaterItems = serverOnly(\n  \"listRepeaterItems()\",\n  \"Read repeater items in a Server Component and pass them down.\",\n);\nexport const getRepeaterItemBySlug = serverOnly(\n  \"getRepeaterItemBySlug()\",\n  \"Resolve the item in a Server Component (your [slug]/page.tsx) and pass it down.\",\n);\nexport const getFieldValue = serverOnly(\n  \"getFieldValue()\",\n  \"Read the value in a Server Component and pass it down as a prop.\",\n);\n\nexport type { GRepeaterProps, RepeaterItemProps } from \"./react/Repeater\";\nexport type {\n  GRState,\n  GRRole,\n  GRMember,\n  GRViewer,\n  GRAsset,\n  GRRepeaterItem,\n  OverrideRow,\n  OverrideValue,\n  OverrideType,\n  PolymorphicProps,\n  HTMLKeys,\n} from \"./core/types\";\nexport type {\n  GRConfig,\n  GRPrefetch,\n  GRMembershipAdapter,\n  GRInviteEvent,\n  GRStorageAdapter,\n  GRUploadTarget,\n  GRRepeaterAdapter,\n  GRDBAdapter,\n  GRAuthAdapter,\n  GRSession,\n  GRStorageRow,\n  AuthResult,\n} from \"./core/adapter-types\";\n"],"mappings":"AASA,SAAS,aAAa;AACtB,SAAS,gBAAgB;AAEzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AASP,SAAS,WAAW,MAAc,MAAc;AAC9C,SAAO,IAAI,UAA4B;AACrC,UAAM,IAAI;AAAA,MACR,cAAc,IAAI,sCAAsC,IAAI;AAAA,IAG9D;AAAA,EACF;AACF;AAEO,MAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;AACO,MAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AACF;AACO,MAAM,YAAY;AAAA,EACvB;AAAA,EACA;AACF;AACO,MAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AACF;AACO,MAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AACF;AACO,MAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;","names":[]}
+{"version":3,"sources":["../src/index.client.ts"],"sourcesContent":["// Client-graph entry. `import ... from \"@guard-rail/core\"` resolves here from a\n// Client Component (see \"exports\" in package.json) and to ./index from a\n// Server Component, so an app uses one import path everywhere.\n//\n// Nothing server-only may be imported here — this is bundled for the browser.\n// Server Actions are fine: a \"use server\" module is replaced by references in\n// the client bundle, which is what lets an app build its own team/repeater UI\n// in a Client Component.\n\nexport { GRail } from \"./react/GRail/universal\";\nexport { useGRail } from \"./react/Provider\";\n\nexport {\n  listTeam,\n  inviteMember,\n  updateMemberRole,\n  removeMember,\n  createAssetUpload,\n  listAssets,\n  setPasswordAction,\n  skipSetPasswordAction,\n} from \"./server/actions\";\nexport {\n  addRepeaterItem,\n  removeRepeaterItem,\n  reorderRepeaterItems,\n} from \"./server/repeaterActions\";\n\n/**\n * Stand-ins for the server-only exports, so importing one from a Client\n * Component fails with an explanation instead of an undefined-is-not-a-function\n * deep in a render. Also what a tool that doesn't set the \"react-server\"\n * condition (a test runner, a plain Node script) gets from the package root —\n * `@guard-rail/core/server` is the explicit path to the real ones there.\n */\nfunction serverOnly(name: string, hint: string) {\n  return (..._args: unknown[]): never => {\n    throw new Error(\n      `Guardrail: ${name} only works in a Server Component. ${hint} ` +\n        `(If this isn't a Client Component, your tooling may not set the ` +\n        `\"react-server\" condition — import from \"@guard-rail/core/server\" instead.)`,\n    );\n  };\n}\n\nexport const withGuardrail = serverOnly(\n  \"withGuardrail()\",\n  \"Call it in your root layout, which is a Server Component.\",\n);\nexport const configureGuardrail = serverOnly(\n  \"configureGuardrail()\",\n  \"Configuration is applied by withGuardrail() in your root layout.\",\n);\nexport const GRepeater = serverOnly(\n  \"<GRepeater>\",\n  \"Render it in a Server Component and pass it into this one as children or a prop.\",\n);\nexport const listRepeaterItems = serverOnly(\n  \"listRepeaterItems()\",\n  \"Read repeater items in a Server Component and pass them down.\",\n);\nexport const getRepeaterItemBySlug = serverOnly(\n  \"getRepeaterItemBySlug()\",\n  \"Resolve the item in a Server Component (your [slug]/page.tsx) and pass it down.\",\n);\nexport const getFieldValue = serverOnly(\n  \"getFieldValue()\",\n  \"Read the value in a Server Component and pass it down as a prop.\",\n);\n\nexport type { GRepeaterProps, RepeaterItemProps } from \"./react/Repeater\";\nexport type {\n  GRState,\n  GRRole,\n  GRMember,\n  GRViewer,\n  GRAsset,\n  GRRepeaterItem,\n  ActionState,\n  SetPasswordState,\n  OverrideRow,\n  OverrideValue,\n  OverrideType,\n  PolymorphicProps,\n  HTMLKeys,\n} from \"./core/types\";\nexport type {\n  GRConfig,\n  GRPrefetch,\n  GRMembershipAdapter,\n  GRInviteEvent,\n  GRStorageAdapter,\n  GRUploadTarget,\n  GRRepeaterAdapter,\n  GRDBAdapter,\n  GRAuthAdapter,\n  GRSession,\n  GRStorageRow,\n  AuthResult,\n  AuthRedirectParams,\n} from \"./core/adapter-types\";\n"],"mappings":"AASA,SAAS,aAAa;AACtB,SAAS,gBAAgB;AAEzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AASP,SAAS,WAAW,MAAc,MAAc;AAC9C,SAAO,IAAI,UAA4B;AACrC,UAAM,IAAI;AAAA,MACR,cAAc,IAAI,sCAAsC,IAAI;AAAA,IAG9D;AAAA,EACF;AACF;AAEO,MAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;AACO,MAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AACF;AACO,MAAM,YAAY;AAAA,EACvB;AAAA,EACA;AACF;AACO,MAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AACF;AACO,MAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AACF;AACO,MAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;","names":[]}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { withGuardrail } from './server/wrapper.js';
-export { createAssetUpload, inviteMember, listAssets, listTeam, removeMember, updateMemberRole } from './server/actions.js';
+export { createAssetUpload, inviteMember, listAssets, listTeam, removeMember, setPasswordAction, skipSetPasswordAction, updateMemberRole } from './server/actions.js';
 export { GRail } from './react/GRail/index.js';
 export { GRepeater, GRepeaterProps, RepeaterItemProps } from './react/Repeater/index.js';
 export { configureGuardrail } from './core/config.js';
@@ -7,7 +7,7 @@ export { getRepeaterItemBySlug, listRepeaterItems } from './server/repeaterData.
 export { getFieldValue } from './server/fieldData.js';
 export { addRepeaterItem, removeRepeaterItem, reorderRepeaterItems } from './server/repeaterActions.js';
 export { useGRail } from './react/Provider.js';
-export { GRAsset, GRMember, GRRepeaterItem, GRRole, GRState, GRViewer, HTMLKeys, OverrideRow, OverrideType, OverrideValue, PolymorphicProps } from './core/types.js';
-export { AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget } from './core/adapter-types.js';
+export { ActionState, GRAsset, GRMember, GRRepeaterItem, GRRole, GRState, GRViewer, HTMLKeys, OverrideRow, OverrideType, OverrideValue, PolymorphicProps, SetPasswordState } from './core/types.js';
+export { AuthRedirectParams, AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget } from './core/adapter-types.js';
 import 'react/jsx-runtime';
 import 'react';