Templates moved BA's tables to a dedicated `better_auth` schema
(insforge-templates#28). The doc was still teaching the old
public+REVOKE model; sync it.
Removed:
- Entire "Lock down PostgREST exposure (REQUIRED)" section (15 lines).
- "DATABASE_URL must keep superuser-grade privileges" callout — no
more REVOKE means no risk of a tightened DATABASE_URL silently
breaking sign-up.
- Organization plugin REVOKE block (5-line SQL + verify curl text).
- Plugin REVOKE template table — every plugin's tables inherit
`search_path=better_auth` automatically.
- Two Common Mistakes rows: "Skipping the REVOKE block" and
"Connecting BA as anon/authenticated after REVOKE" — both no
longer applicable.
Replaced with:
- Three-line schema-layout intro at the top of the guide showing
auth.* / better_auth.* / public.* ownership.
- "Schema setup + first migrate" subsection with `CREATE SCHEMA`
one-liner + a callout explaining why this is sufficient (PostgREST
exposes only `public` by default; dashboard reaches `better_auth`
through the admin route's postgres superuser pool).
- New `lib/auth.ts` example with `pool.on('connect')` setting
`search_path TO better_auth, public` — the canonical pg method
per BA's own docs since pg.Pool doesn't take a schema option.
- New Common Mistakes rows: forgetting `CREATE SCHEMA` before
migrate; FK'ing without schema qualification.
Updated:
- Manual-integration numbered workflow: drop the REVOKE step,
insert the CREATE SCHEMA step.
- FK example in the database-setup section: `REFERENCES public."user"(id)`
→ `REFERENCES better_auth."user"(id)`.
- "FK to BA users" section: prescribed FK is now `better_auth.user(id)`
(not `public.user(id)`).
- Plugin section's "rule of thumb": `\dt better_auth.*` (not `public.*`).
- All REVOKE-template SQL in plugin sections — gone.
Net change: 96 lines edited (48 insertions, 48 deletions). Word count
4260 → 4482 (+5%) because the explanatory schema-layout + new Common
Mistakes rows are slightly longer than the dropped sections; acceptable
for the clarity gain.
Verified end-to-end against current insforge main (v2.1.0) via
insforge-templates#28's branch — see that PR for the test matrix.
Ran the writing-skills TDD methodology against the BA integration guide:
dispatched a baseline subagent to do the integration with no doc access
(RED), then a second subagent reading the doc (GREEN). Compared their
outputs to identify what the doc teaches well vs where it has gaps.
The doc PASSED retrieval testing — the GREEN agent produced correct
bridge route, REVOKE matrix, and requesting_user_id() helper just by
reading the relevant sections. But three real issues surfaced:
1. Hono bridge example contradicted the Next bridge on PII. The Next
route's comment says "Don't add email or other PII"; the Hono one
inlined `email: session.user.email` 400 lines later. GREEN agent
flagged this as an internal contradiction. Removed the email claim,
added a back-reference to the Next route's no-PII comment, and
added the same `Cache-Control: no-store` header for parity.
2. The "DATABASE_URL must keep superuser-grade privileges" warning was
buried in the Common Mistakes table near the bottom. Promoted it
into a callout immediately under the REVOKE block, where the foot-
gun actually fires (a user who tightens DATABASE_URL to the
`authenticated` role after the REVOKE silently breaks BA sign-up).
3. The doc taught `requireEnv()` as the canonical pattern at lines
60-66 but used `process.env.X!` 12 times after on the SERVER side
— internal inconsistency a junior copy-paster would inherit.
Standardized server-side reads on `requireEnv`. Kept `!` for
`NEXT_PUBLIC_*` (those are bundler-inlined; a module-load check
would just fire in the browser anyway) and added a one-line
comment near the requireEnv definition explaining the asymmetry.
Also tightened `skills/insforge-integrations/SKILL.md` description:
dropped the workflow-summary tail ("Covers provider-specific dashboard
setup, client/server code…") since per writing-skills CSO guidance, a
description that summarizes the body trains Claude to read the
description and skip the actual content. The description now states
only when to use the skill.
The Vite/React skeleton was demonstrating the same Vite-proxy +
Origin-rewrite pattern that's already documented in prose with full
code blocks (the "Vite / React-only setups" section, ~109 lines
including a complete vite.config.ts and Hono bridge route).
Same drift logic that retired examples/better-auth-nextjs: no
CLI/CI keeps the example accurate, every @insforge/sdk or BA bump
risks a stale snippet. The doc IS the canonical reference.
If a real "clone-and-run" Vite story becomes worth the maintenance,
ship it through the CLI: a `vite` base template + the existing
better-auth overlay, same model as nextjs.
PR #44 is now 2 files: the SKILL.md edit and the integration guide.
The Next skeleton was duplicating what `insforge create --auth
better-auth` (CLI #98) and the templates repo's auth-providers/
better-auth/ overlay produce. We just had drift between the two
copies — the project_admin REVOKE fix had to land twice — so the
duplication is real maintenance cost.
Drop the Next skeleton entirely; point the doc at the CLI command
instead. Vite/React skeleton stays — the CLI doesn't scaffold React
yet, so it's still the canonical reference for that pattern.
Reduces this PR from 33 files to 13.
The dashboard's record browser switched from /database/records (PostgREST
passthrough, runs as the project_admin Postgres role) to
/database/admin/tables/.../records (backend AdminRecordService → postgres
superuser pool). Studio inspection is now role-independent, so the
"REVOKE from project_admin only if you want full lockdown" caveat was
misleading — there's no trade-off, just REVOKE from it.
Updated the core REVOKE block, the Organization plugin block, and the
plugin REVOKE-template table.
Replaces the description with the canonical InsForge positioning:
"The backend platform for AI-native developers. A Postgres-based
backend with auth, storage, compute, hosting, and AI gateway. Built
for coding agents."
Updates keywords to match the surface area called out in the tagline
(postgres, auth, storage, compute, hosting, ai-gateway) and swaps
agent-native for ai-native / coding-agents to mirror the marketing copy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reframes the plugin description so the InsForge value prop — agent-native
BaaS for agent-native builders — is the first thing a marketplace browser
sees, before the feature list. Adds agent-native and ai-agents keywords
to improve discoverability for builders searching the directory.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds .claude-plugin/plugin.json so this repo can be submitted to the
official Claude Code plugin marketplace
(anthropics/claude-plugins-official) via the in-app submission form at
claude.ai/settings/plugins/submit.
Also aligns the license field across the three SKILL.md files that
declared Apache-2.0 to MIT, matching the LICENSE file at the repo root
and avoiding inconsistency a marketplace reviewer would flag.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Clarify what end users see on Google's sign-in screen with shared keys
(insforge.dev) vs. custom credentials (insforge.app) and what the project
owner needs to do in each case to rebrand.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Critical correction. The published @insforge/sdk@1.2.6 does NOT
expose client.setAccessToken on the public client class — only on
TokenManager. Both example skeletons were calling client.setAccessToken
directly, which would throw "is not a function" at runtime. The CLI
scaffold was already correct (feature-detect helper); the standalone
example skeletons were not.
Verified by importing the published 1.2.6 SDK directly:
client.setAccessToken → undefined
client.getHttpClient().setAuthToken → function
client.realtime.tokenManager.setAccessToken → function
Changes:
- Both skeleton lib/insforge.ts files now use the same setBridgeToken
helper the CLI scaffold uses (feature-detects so it stays correct
when public method ships in 1.3.0)
- Skill doc Pattern A code block adopts the helper; the explanatory
note is rewritten to match reality (1.3.0 ships public method,
1.2.x needs dual-update)
- Sign-out section, Realtime section, and Common Mistakes table
entry all reference the helper instead of the non-existent
public method
- React skeleton README updated
Verified post-fix end-to-end on ba-sdk-test: Vite SPA signup → bridge
JWT → RLS-scoped INSERT all green with the corrected helper.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@insforge/sdk@1.3.0 doesn't exist on npm — the latest published
version is 1.2.6, which already includes the public setAccessToken
API the skeletons depend on. Both example skeletons' package.json
were failing npm install on the stale ^1.3.0 pin.
Also flips every "SDK ≥ 1.3.0" reference in the skill doc and
example READMEs to 1.2.6 so the version threshold matches reality.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Recommended Workflow section now leads with the four-line CLI flow
(link → install → setup → dev) and frames the rest of the doc as a
reference layer: what got scaffolded, why, and how to extend it.
Manual workflow stays as a one-paragraph callout for users who can't
or won't use the CLI, with each numbered step still anchored to its
own section below.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
If a user lands on this guide without BA already configured, give them
two paths: the InsForge CLI flag (one-shot) for users in our flow, or
better-auth/skills (the canonical BA scaffolder) for users coming from
outside. This skill covers the InsForge integration layer, not generic
Better Auth setup, so we shouldn't reinvent the BA scaffolder.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tracks the parallel CLI rename: the underlying OSS endpoint surfaces
Fly machine lifecycle events (start/stop/exit/restart), not container
stdout/stderr. The new command name is honest about that.
`compute logs` will return as a separate command for actual container
stdout/stderr streaming when that feature lands.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add `CREATE EXTENSION IF NOT EXISTS pgcrypto` before gen_random_uuid()
so the SQL block runs on a fresh DB. Idempotent on existing stacks.
- Validate the bridged token before piping it into setAccessToken so a
malformed bridge response throws cleanly instead of silently clearing
auth state.
- Narrow the React effect dep from session.data?.user to
session.data?.user?.id — avoids resetting the refresh interval if the
auth library returns a new user object instance with the same id.
- Pattern B: pass explicit { algorithm: 'HS256', expiresIn: '1h' } to
jwt.sign and drop the manual exp claim. Aligns with the bridge route
and the service-token mailer.
CodeRabbit also flagged HTML escaping in the email-template snippet.
Skipping that — production code should use react-email/mjml; for an
example demonstrating client.emails.send, a 7-line escape helper is
more noise than the snippet's worth.
Re-ran the 12-check Next.js e2e: signup → bridge → RLS isolation → REVOKE
→ sign-out, all green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fixes two issues flagged on PR #50:
1. Lines 363 + 524 described an outdated deploy workflow ("requires
flyctl + FLY_API_TOKEN env var", "backs up fly.toml then restores
the original"). Current main (CLI #89, compute v3.2):
- Image mode (--image <url>): needs no local tooling.
- Source mode (compute deploy <dir>): needs flyctl on PATH only.
The cloud mints a per-app deploy token; the CLI injects it into
the spawned flyctl process. Users do NOT set FLY_API_TOKEN.
flyctl invents a fly.toml if one doesn't exist — no backup dance.
2. Line 143 listed `--env` without the `<json>` placeholder, breaking
parity with the deploy line above it. Now `--env <json>` everywhere.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sibling to better-auth-nextjs/, demonstrating Pattern A (Vite proxy) from
the integration guide's new "Vite / React-only setups" section. The
auth/SDK code is identical — only the route-handler shape changes (BA
runs in a separate process, not Next route handlers) and env vars use
import.meta.env.VITE_* instead of process.env.NEXT_PUBLIC_*.
Files:
- vite.config.ts: proxies /api → :3030 with the proxyReq Origin rewrite
so BA's CSRF check sees its own baseURL (otherwise sign-out 403s).
- src/auth-client.ts: createAuthClient pointed at the SPA origin.
- src/insforge.ts: same useInsforgeClient hook as the Next skeleton —
framework-agnostic React, with 'use client' dropped and env-var
access switched to import.meta.env.VITE_*.
- src/App.tsx: single-component SPA with sign-up/in form + notes list.
- README.md: setup against the sibling Next skeleton as the BA host,
with Pattern B (cross-origin, no proxy) escape hatch noted.
- package.json: pinned @insforge/sdk ^1.3.0 (the version that exposes
client.setAccessToken).
Verified end-to-end: 7-check e2e drives signup → bridge JWT → RLS-isolated
note CRUD → sign-out via the Vite origin, all through the proxy. All pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The skill previously documented only the Next.js path with one short
"Cross-origin (React SPA without a Next.js server)" subsection. This
restructures it to give Vite/React a first-class section alongside Next.js,
and updates Pattern A to use the new public client.setAccessToken(token)
method (SDK ≥ 1.3.0) instead of the @ts-expect-error tokenManager workaround.
Skill doc changes:
- New "Vite / React-only setups" section covering Pattern A (Vite proxy)
and Pattern B (true cross-origin), with a Hono bridge-route example for
non-Next servers + Express equivalent.
- Renamed Next-specific subheads ("Better Auth route handlers (Next.js)",
"The bridge route (Next.js)") with cross-references.
- Pattern A code now uses client.setAccessToken(token) plus a note
explaining the older two-step workaround for SDK < 1.3.0.
- Env var table split into Next (NEXT_PUBLIC_*) vs Vite (VITE_*) variants.
- Two new "Common Mistakes" entries:
· Vite proxy needs Origin rewrite (or trustedOrigins) — sign-out 403s
otherwise; sign-up's looser handling masks the bug
· Cross-origin with sameSite:'none' still requires trustedOrigins
- Workflow + intro reference both runnable skeletons.
Next skeleton changes:
- lib/insforge.ts: replace setBridgeToken helper (with @ts-expect-error
tokenManager access) with one client.setAccessToken() call.
- package.json: bump @insforge/sdk to ^1.3.0 (next minor exposing the
new public method).
Both gotchas were caught while writing a sibling Vite skeleton — the
proxy 403 and the cross-origin trustedOrigins ones aren't theoretical.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pass over the previous commit per the writing-skills token-efficiency
+ cross-reference-over-duplication guidance:
- SKILL.md: trimmed implementation specifics that don't help an agent
pick the flag (e.g. "the server decrypts existing env, applies set/
unset, re-encrypts" — true but not actionable from the CLI). Net
result is 46 words *shorter* than the pre-flag baseline despite
documenting --env-file, --env-set, --env-unset, the lifecycle-only
reality of `compute logs`, and the audit-log behavior of `compute
delete`.
- references/compute-deploy.md: tightened the env-rotation section
(single example with both --env-set and --env-unset, removed the
separate "wholesale" example since a one-liner conveys the contrast
inline) and replaced duplicate prose in Notes with a section link.
- Reordered the env-rotation guidance so the *common* path (partial
merge) appears first; the wholesale replace is the warning-flagged
alternative.
No behavior change.
Three additions to the compute section so AI agents reach for the right
flags instead of cargo-culting --env <inline-json> for every operation.
1. compute deploy --env-file <path> — accepts a standard .env file. The
skill's deploy command line + options table + examples now mention it
alongside --env, with the mutual-exclusion noted.
2. compute update --env-set KEY=VALUE / --env-unset KEY (repeatable) —
partial env merge that targets the new envVarsPatch endpoint. The doc
explains *why* this exists: the GET path doesn't return env values, so
wholesale --env requires you to know all the other secrets to avoid
wiping them. A short "Updating env vars after deploy" section in the
compute-deploy reference covers wholesale vs partial.
3. Honesty pass on `compute logs` and `compute delete`. `compute logs`
shows Fly **lifecycle events** only — not container stdout/stderr —
and the SKILL.md text now says so explicitly so agents don't tell
users "check the logs" expecting stdout. `compute delete` notes the
audit-log snapshot exists for accidental-delete recovery.
No code change in this skills repo.
- Profile / stats / notes panels with a dark-mode design
- Notes CRUD (add, edit inline, delete with optimistic rollback)
- Bridge-state indicator + sign-out wired through useInsforgeClient
- Styled sign-in / sign-up to match
Verified end-to-end on a live InsForge stack: bridge JWT carries minimal
claims, RLS isolates SELECT/UPDATE/DELETE per user, REVOKE blocks anon
reads on the BA tables.
- Bridge route: drop email claim, add Cache-Control: no-store
- Pattern A: use setBridgeToken (HTTP + realtime in lockstep)
- SQL: rerun-safe with IF NOT EXISTS / DROP POLICY IF EXISTS
Critical (1):
- app/layout.tsx — replace `React.ReactNode` (no React import) with
`import type { ReactNode } from 'react'`. Cleaner under strict mode
+ Next 15's auto-runtime jsx transform.
Major (3):
- app/api/insforge-token/route.ts — drop the `email` claim from the
bridge JWT. RLS only needs `sub`; including email is unnecessary
PII in a token that may be logged. Also add `Cache-Control: no-store`
so the bridge response isn't cached anywhere — bridge tokens are
short-lived and per-session.
- sql/01-init.sql — replace `DROP TABLE notes CASCADE` + bare CREATE
POLICY with `CREATE TABLE IF NOT EXISTS` plus `DROP POLICY IF EXISTS`
before each `CREATE POLICY`. Reruns are now non-destructive and
idempotent — won't blow away user data on `db:setup`.
- references/better-auth.md — sign-out example was clearing only the
HTTP token; aligned it with the dual-update `setBridgeToken` pattern
the rest of the doc uses, plus an inline fallback that calls both
setAuthToken(null) and tokenManager.setAccessToken(null) explicitly.
Minor (5):
- app/sign-in/page.tsx, app/sign-up/page.tsx — wrap submit handlers
in try/catch so transport/runtime errors actually surface to the
user instead of being swallowed; replace placeholder-only inputs
with explicit <label htmlFor=...> + autocomplete attributes for a11y.
- lib/auth.ts and app/api/insforge-token/route.ts — replace
`process.env.X!` non-null assertions with a `requireEnv()` helper
that throws a named-var error at module load instead of failing
later on undefined. Bridge route gets the same treatment for the
JWT secret.
- README.md — clarify the OAuth-providers bullet: GitHub/Google in
prose, lowercase `github` key inside the BA `socialProviders` config
(the key is lowercase by Better Auth API convention; CodeRabbit's
suggestion to capitalize would have broken the config).
- .env.example — alphabetize within the InsForge public group so
dotenv-linter is happy (ANON_KEY before BASE_URL).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Apply CSO (Claude Search Optimization) so the new
storage/postgres-rls.md guide actually gets routed to. Adds three
classes of trigger:
1. Pattern names — owner-only, public-read, path-scoped, team-shared,
mixed REST + S3 — so users describing the *shape* of the bucket
they want hit this skill.
2. Symptom phrases — "user can't see a file they just uploaded" and
"S3-uploaded files don't appear in the user API" — the actual
strings users type when they're stuck.
3. Concrete identifiers — uploaded_by, auth.jwt(), storage.foldername,
storage.objects — what someone copy-pasting from an error or an
example will paste in.
Same pattern PR #39 used for s3-gateway triggers.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Document the storage RLS model that ships with InsForge migration 036.
Covers the auth.jwt() helper, storage.foldername / filename / extension
path helpers, and five copy-pasteable patterns:
- Owner-only (the auto-installed default for existing projects)
- Public-read (galleries, public assets, CDN-style)
- Path-scoped (first folder = sub, via storage.foldername)
- Team-shared (membership-table check via EXISTS)
- Mixed REST + S3 (handling the NULL uploaded_by caveat)
Each pattern: behavior table, ready-to-paste SQL, common pitfalls.
Plus performance tips (hoist auth.jwt() into a SELECT subquery, index
policy columns), a checklist before shipping, and a cross-link to
database/postgres-rls.md.
Updates skills/insforge/SKILL.md to:
- Add the new guide to the Guides table.
- Mention "write RLS policies for buckets" in the Storage module row.
Pairs with InsForge/InsForge#1161 (the platform PR shipping RLS on
storage.objects + auth.jwt() + storage.foldername helpers).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the bland "in progress" callout with an explicit private-preview
notice that tells readers exactly what they can ask the InsForge team
for: access, quota raises, private-registry credentials, issue reports.
This keeps the door open for support routing without a separate FAQ.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The cloud-backend now retries Fly's transient 400 MANIFEST_UNKNOWN on
launchMachine (backoff [2s, 4s, 8s], 4 attempts) and passes Fly 4xx
through structured (COMPUTE_IMAGE_NOT_AVAILABLE for the manifest race,
COMPUTE_FLY_API_ERROR otherwise) instead of letting them surface as
unhandled 500s.
Adds:
- Two error rows in the Common errors table for the new structured codes
- A FAQ entry explaining the registry alias propagation race so users
who do see the rare 4xx know that a re-run is the right action
- Tightens the existing COMPUTE_QUOTA_EXCEEDED row from earlier WIP
Verified against staging today via end-to-end CLI source-mode deploys
(api-beta.insforge.dev / cloud v1.2.11-compute2 / OSS v2.1.3-compute):
flyctl Depot remote build → image push → cloud launches machine in
[running] state — the 500 that previously surfaced from this race is
gone.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drop the "5 minutes" / "1 hour" examples from interval-syntax
explanations. Anyone reaching for interval form is doing it for
sub-minute cadence — minutes/hours are already the natural fit
for 5-field cron and listing them as interval examples just
muddies the "when to pick which" call.
Single canonical example everywhere: "30 seconds".
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Source mode no longer needs Docker locally — the CLI now uses
`flyctl deploy --remote-only --build-only` with the cloud-minted per-app
token, so the build runs on Fly's remote builder and is pushed to
registry.fly.io directly. User-facing requirement is now just `flyctl`
on PATH (no Docker daemon).
Updates the SKILL.md command list, the "two modes" non-obvious behavior
note, and the compute-deploy.md reference (worked example, behind-the-
scenes steps, error table, FAQ entries on tooling and token scope).
Companion to CLI feat/compute-v3-flyctl-no-docker.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
yaowenc2