@stnd/account

A comprehensive, self-contained authentication module for the Standard Garden framework, leveraging BetterAuth.

ELI5

Login, sessions, “sign in with Google”, passkeys (Face ID/Touch ID) — all of it, already wired together, so an app doesn’t reinvent auth from scratch. It’s a Standard module: add it to moduleLoad, point it at a D1 database, and the /api/auth/* routes + the sign-in UI just exist.

Install: moduleLoad: ["@stnd/account"] in astro.config.mjs, then follow “Getting Started” below (D1 schema + env vars — there’s real setup, this isn’t zero-config).

Use it (client-side sign-in):

import { signIn } from "@stnd/account/client";
await signIn.social({ provider: "google" });

Features

• Google OAuth: Pre-configured social login integration.
• Passkeys: Built-in support for Touch ID / Face ID / WebAuthn.
• Magic Links: Ready to be wired up with email service providers.
• Astro Integration: Automatic API route generation (/api/auth/[…all]) and middleware protection.
• D1 Compatibility: Seamlessly integrates with Cloudflare D1 and cloudflare:workers environment variables.

Getting Started

1. Database Setup

This module requires specific tables in your Cloudflare D1 database. A schema.sql file is provided in this directory.

When you’re ready to test locally or deploy, apply the schema using Wrangler:

wrangler d1 execute <YOUR_DB_NAME> --local --file=packages/account/schema.sql

(Remove --local when applying to your production database).

2. Environment Variables

Ensure your application’s .dev.vars (for local development) and Cloudflare environment secrets contain the following:

BETTER_AUTH_SECRET="your-generated-secret"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

Note: Generate a secure secret using npx @better-auth/cli secret or openssl rand -base64 32.

3. Application Integration

In your app’s astro.config.js (e.g., apps/ade/astro.config.js), ensure the module is loaded:

import standard from "@stnd/core";

export default defineConfig({
  integrations: [
    standard({
      moduleLoad: [
        "@stnd/account",
        // ... other modules
      ],
      account: {
        // Optional Configuration overrides (defaults fallback to env vars)
        // db: env.DB, // D1 database binding
        // rpName: "My Custom App", // Passkey Relying Party Name
        // rpID: "my-app.com",      // Passkey Relying Party ID
        // baseURL: "https://auth.my-app.com",
        // trustedOrigins: ["https://my-app.com"]
      },
    }),
  ],
});

4. Google OAuth Setup

To enable Google Login, you must configure a project in the Google Cloud Console:

1. Create Project: Start a new project (e.g., Utopie-ADE).
2. OAuth Consent Screen: 
   • Set User Type to External.
   • Add your email as a Test User (required while the app is in “Testing” status).
3. Credentials: 
   • Create OAuth client ID of type Web application.
   • Authorized JavaScript origins: http://localhost:8083 (and your production domain).
   • Authorized redirect URIs: http://localhost:8083/api/auth/callback/google (and https://your-domain.com/api/auth/callback/google).
4. Copy IDs: Paste the Client ID and Secret into your .env or .dev.vars.
5. Passkey (WebAuthn) Setup
   Passkeys require a secure context (HTTPS or Localhost).

• Development: Use http://localhost:8083 or your local port. Note that some browsers require the rpID to match the exact hostname. The module defaults to localhost.
• Production: Ensure env.RP_ID (or account.rpID in astro.config.js) is set to your domain (e.g., ade.stnd.build). You should also configure env.RP_NAME (or account.rpName) for the prompt display.

6. Client Usage

In your Svelte frontend components, you can import the pre-configured better-auth clients:

import { signIn, signUp, useSession, signOut } from "@stnd/account/client";

// Example: sign in with Google
const handleSignIn = async () => {
  await signIn.social({ provider: "google" });
};

Maintenance & Troubleshooting

Database Adapter Errors

If you see Failed to initialize database adapter or db.insertInto is not a function, ensure that the kysely and kysely-d1 dependencies are correctly installed in the module workspace and that the D1Dialect is being passed the valid D1 binding from the request context.

Origin Mismatch (403 Forbidden)

Ensure baseURL in auth.js matches the port your app is actually running on (e.g., 8083 for ADE). BetterAuth’s CSRF protection is strict about port numbers.

Notes / Observations

(jot down anything noticed here — quirks, gotchas, ideas)

Todo

• [ ] Nothing tracked yet.