Configuration Reference ​

Complete reference for teenybase.ts (or teeny.config.ts) — every option, every type, every field.

Teenybase is configured through a single TypeScript object that satisfies the DatabaseSettings type. This page documents every option.

Quick Reference: What Field Type Should I Use? ​

For the full list with all compatible sqlType options, see Field Types below.

DatabaseSettings (top-level) ​

export default {
    appUrl: 'http://localhost:8787',
    jwtSecret: '$JWT_SECRET',
    tables: [],

    // Optional
    appName: 'My App',
    jwtIssuer: 'my-app',
    jwtAlgorithm: 'HS256',
    authProviders: [],                          // empty array is valid
    authCookie: { name: 'auth_token' },         // `name` is required when authCookie is set
    email: {                                    // when set, `from` and `variables` are required
        from: 'noreply@example.com',
        variables: {
            company_name: 'My App',
            company_url: 'https://my-app.com',
            company_address: '123 Main St',
            company_copyright: '2026 My App',
            support_email: 'support@my-app.com',
        },
        // pick one provider: mailgun / resend / cloudflare (see Email Configuration below)
    },
    actions: [],
    // version: stamped automatically by the CLI on each apply
} satisfies DatabaseSettings

Table Definition (TableData) ​

{
    name: 'posts',
    fields: [/* ... */],

    // Optional
    autoSetUid: true,
    extensions: [/* ... */],   // include a 'rules' extension, or set public: true
    public: false,
    triggers: [/* ... */],
    indexes: [/* ... */],
    fullTextSearch: {/* ... */},
    r2Base: 'posts',
    idInR2: false,
    autoDeleteR2Files: true,
    allowMultipleFileRef: false,
    allowWildcard: false,
}

Field Definition (TableFieldData) ​

{
    name: 'title',
    type: 'text',
    sqlType: 'text',

    // Optional — constraints
    primary: false,
    autoIncrement: false,
    unique: false,
    notNull: false,
    default: sql`CURRENT_TIMESTAMP`,
    check: sql`json_valid(config)`,
    collate: 'NOCASE',

    // Optional — foreign key
    foreignKey: {
        table: 'users',
        column: 'id',
        onDelete: 'CASCADE',
        onUpdate: 'CASCADE',
    },

    // Optional — API behavior
    usage: 'record_uid',
    noSelect: false,
    noInsert: false,
    noUpdate: false,
}

Foreign Key Options ​

foreignKey: {
    table: 'users',       // Referenced table name
    column: 'id',         // Referenced column name
    onDelete: 'CASCADE',  // Action on parent delete
    onUpdate: 'CASCADE',  // Action on parent update
}

Field Types ​

The type property controls how teenybase treats the field at the API level — validation, serialization, and extension behavior.

SQL Types ​

The sqlType property maps to the actual SQLite column type used in DDL.

Field Usages ​

Usages give fields semantic meaning. Extensions detect usages automatically and wire up behavior — you don't need to write any handler code.

Record Usages ​

Auth Usages ​

These are recognized by the Auth Extension and enable automatic authentication behavior.

Admin-only auth columns. A non-admin request cannot write the auth_audience, auth_email_verified or auth_password_salt columns: sign-up, insert, update, edit and action steps that set one get 403 with a field error ("role can only be set by an admin"), even when the rules and noInsert/noUpdate would allow it. New users get the column's default, so give role a default if every user should start with one ({...fields.role, default: sqlValue('guest')}). Admin tokens can set them (promote a user with an admin update); action steps with applyTableRules: false can too. A non-admin email change (when email is not noUpdate) is validated like sign-up and resets email_verified unless the address is unchanged. See Security: Privileged auth fields.

Extensions ​

Auth Extension (TableAuthExtensionData) ​

Adds authentication endpoints to a table — sign-up, login, password reset, email verification, OAuth, and JWT management.

{
    name: 'auth',
    jwtSecret: '$JWT_SECRET_USERS',   // required
    jwtTokenDuration: 3600,           // required (seconds)
    maxTokenRefresh: 5,               // required (0 = unlimited)
} as TableAuthExtensionData

JWT (required):

Passwords:

Email & verification:

OAuth:

Email Templates ​

emailTemplates: {
    verification: {
        subject: 'Verify your email',
        layoutHtml: '<div>{{EMAIL_CONTENT}}</div>', // custom inner template (wrapped in base + message layouts)
        variables: { custom_key: 'value' },
        tags: ['verification'],
    },
    passwordReset: {
        subject: 'Reset your password',
        layoutHtml: ['<html>{{EMAIL_CONTENT}}</html>', '<div>{{EMAIL_CONTENT}}</div>', '<p>Reset</p>'], // full template stack
    },
}

The default email templates (baseLayout1, messageLayout1, actionLinkTemplate, actionTextTemplate) are exported from teenybase/worker for use in custom layouts.

Endpoints added: See API Endpoints

JWT Claims ​

Auth tokens issued by teenybase contain these claims (defined in src/types/jwt.ts):

How JWT signing works: The signing key is globalJwtSecret + tableJwtSecret (concatenated). Both resolve $-prefixed env vars at runtime.

Rules Extension (TableRulesExtensionData) ​

Adds row-level security via expression-based access rules. Rules are compiled to SQL WHERE clauses and injected into every query.

{
    name: 'rules',
    listRule: 'auth.uid == owner_id',
    viewRule: 'auth.uid == owner_id',
    createRule: 'auth.uid != null',
    updateRule: 'auth.uid == owner_id',
    deleteRule: 'auth.uid == owner_id',
}

Conflict clause or: 'REPLACE' (and edit/:id?or=INSERT, which uses it) deletes the conflicting row without running deleteRule, so on a table with rules it is rejected with 403 for non-admin callers unless deleteRule is 'true' and the table has no trigger on that event (INSERT for inserts, UPDATE for updates; SQLite runs a trigger's own writes with the outer OR REPLACE too). On a table with the auth extension it is always admin-only, because auth tables don't allow non-admin deletes. or: 'IGNORE', 'ABORT', 'FAIL' and 'ROLLBACK' are not restricted.

Access Control Defaults ​

Access is deny by default, at two levels:

• A rule that is omitted or null denies that operation (403) to everyone except admins.
• A table with no rules extension at all behaves as if all five rules were null: anonymous and signed-in users get 403 on list, view, insert, update and delete. Admin requests (admin JWT or ADMIN_SERVICE_TOKEN) still work, and so do actions that bypass table rules (sql mode, or steps mode with applyTableRules: false; an FK expansion from such a step into another rules-less table is still denied).

Like rules, default-deny governs the CRUD routes (/api/v1/table/{table}/...) and rule-applying actions. On an auth table, password sign-up goes through createRule (so it is denied too), but login, OAuth sign-in, password reset, email verification and change-password do not use table rules. The /api/v1/files/... download route does not check rules either.

Because a table nobody can reach is almost always a mistake, teeny generate, teeny deploy and teeny build fail when a table has neither a rules extension nor public: true:

Table "notes" has no access rules.
...
Fix each table in one of two ways:
  1. Add a rules extension that says who can do what, ...
  2. Mark it public, ...

Pick one per table:

// 1. Rules (recommended). Omitted rules stay null = denied.
{ name: 'notes', fields: [/* ... */], extensions: [
    { name: 'rules', listRule: 'auth.uid == owner_id', viewRule: 'auth.uid == owner_id',
      createRule: 'auth.uid != null & owner_id == auth.uid', updateRule: 'auth.uid == owner_id', deleteRule: 'auth.uid == owner_id' },
] }

// 1b. Admin-only table: a rules extension with no rules.
{ name: 'audit_log', fields: [/* ... */], extensions: [{ name: 'rules' }] }

// 2. Fully public table: anyone, including unauthenticated requests, can read AND write every row.
{ name: 'guestbook', fields: [/* ... */], extensions: [], public: true }

public: true together with a rules extension is a validation error, because it would be unclear which one applies. For a table that should be readable by everyone but writable only by some users, use rules (listRule: 'true', viewRule: 'true', and stricter write rules), not public.

Upgrading from 0.0.x: tables without a rules extension used to allow full anonymous CRUD. They are now denied, and teeny generate / deploy stop with the error above until you add rules or public: true to each such table. To keep the old behaviour for a table, add public: true to it.

Rule Values ​

Expression Syntax ​

Rules use a JS-like expression language that compiles to parameterized SQL WHERE clauses. All string/number literals in expressions become ? placeholders with bound values, and column names are validated against the table schema. So an expression can never inject SQL, and table rules always apply on top of it. Building an expression from user input still needs quoting: a raw value like `email == '${userInput}'` can close the string literal and change what the expression means (x' | email != ' adds an OR branch). Quote values with JSON.stringify, which produces a valid string literal for any text: where: `email == ${JSON.stringify(userInput)}`.

String literals can hold text in any script, including combining marks, CJK punctuation and emoji (name == '文件（一）.glb'); control characters and invisible format characters (zero-width spaces and joiners, bidi overrides) are rejected with Invalid expression. Column and table names stay ASCII ([a-zA-Z_][a-zA-Z0-9_]*). The same applies to where, select and other expressions sent to the CRUD endpoints.

Available variables:

Operators:

Precedence: comparisons bind tighter than & (AND), which binds tighter than | (OR). a == 1 | b == 2 & c == 3 means a == 1 | (b == 2 & c == 3); use parentheses for anything else. Strings can use single or double quotes; inside a TypeScript string, "status == 'published'" is the usual form. Expressions are flat: there is no SELECT subquery syntax.

SQL functions available in expressions:

Rule Examples ​

// Public read, authenticated write
{
    name: 'rules',
    listRule: 'true',                          // Anyone can list
    viewRule: 'true',                          // Anyone can view
    createRule: 'auth.uid != null',            // Must be logged in to create
    updateRule: 'auth.uid == owner_id',        // Only the owner can update
    deleteRule: 'auth.uid == owner_id',        // Only the owner can delete
}

// Admin-only table
{
    name: 'rules',
    listRule: "auth.role == 'admin'",
    viewRule: "auth.role == 'admin'",
    createRule: "auth.role == 'admin'",
    updateRule: "auth.role == 'admin'",
    deleteRule: "auth.role == 'admin'",
}

// Users can only see/edit their own records
{
    name: 'rules',
    listRule: 'auth.uid == id',
    viewRule: 'auth.uid == id',
    createRule: 'auth.uid == null',                      // Sign-up: only non-authenticated
    updateRule: 'auth.uid == id',                        // role/email_verified stay admin-only regardless
    deleteRule: null,                                    // No one can delete
}

// Posts: the author can edit, but not hand the post to someone else
{
    name: 'rules',
    listRule: 'published == true | auth.uid == author_id',
    viewRule: 'published == true | auth.uid == author_id',
    createRule: 'auth.uid != null & author_id == auth.uid',
    updateRule: 'auth.uid == author_id & new.author_id == author_id',  // omitted author_id = unchanged
    deleteRule: 'auth.uid == author_id',
}

auth.role == 'admin' is safe to rely on: only admins can write the role column (see Admin-only auth columns), so a user cannot sign up as or promote themselves to admin. auth.meta is different: the meta column is writable by the user like any other column their rules allow, so if rules read auth.meta, guard it in the users table with updateRule: "auth.uid == id & new.meta == meta" and a createRule that checks meta.

"Unchanged" checks in updateRule: new.<col> == <col> passes when the request doesn't touch the column and fails when it changes it. Use == (IS, null-safe); with = a NULL column never equals itself, so the rule would block every update of rows where it is NULL.

Common Mistakes ​

• Forgetting null denies access. If you omit a rule, it defaults to null (deny all), and a table with no rules extension denies everything. This is secure by default, but make sure you set rules for endpoints you want accessible. See Access Control Defaults.
• 'true' must be a string. Use 'true' (string), not true (boolean). Boolean true won't work.
• Rules on create vs read. Create rules guard whether the insert can happen. List/view rules filter which records are returned — they don't prevent the query, they limit the results (a hidden record is missing from lists, and view/:id returns 404).
• !column on a nullable column. In SQL, NOT NULL is NULL, which filters the row out. Write deleted_at == null ("not deleted"), not !deleted_at.
• updateRule without an "unchanged" check. updateRule: 'auth.uid == author_id' lets the author set author_id to another user. Add & new.author_id == author_id (see above).

CRUD Extension ​

Auto-included for every table. Provides REST endpoints for CRUD operations.

{ name: 'crud' }

No additional configuration. The CRUD extension registers these routes:

See API Endpoints for full request/response formats.

OpenAPI Extension ​

Auto-generates an OpenAPI 3.1.0 spec from your tables, extensions, and actions.

import { OpenApiExtension } from 'teenybase/worker'

db.extensions.push(new OpenApiExtension(db))        // with Swagger UI (default)
db.extensions.push(new OpenApiExtension(db, false))  // JSON spec only, no Swagger UI

Routes (under /api/v1):

Notes:

• The document title is "Teenybase API" (v1.0.0) — not configurable.
• Routes with incompatible zod schemas (e.g., superRefine) are silently skipped with a console warning.
• An authorization header parameter is auto-injected into every route's spec.

PocketUI Extension ​

Built-in admin panel for browsing tables, viewing/editing records, and managing data.

import { PocketUIExtension } from 'teenybase/worker'

db.extensions.push(new PocketUIExtension(db))

The worker fetches the UI files and serves them from your API's own origin, so the browser only talks to your worker; the worker needs outbound access to jsDelivr. The fallback login page loads Pico CSS 2.1.1 from jsDelivr with Subresource Integrity, and Swagger UI (/api/v1/doc/ui) loads swagger-ui-dist 5.33.2 from jsDelivr.

Routes:

Environment variables:

Cookie behavior:

• Session cookies expire after 1 hour
• teeny-pocket-ui-access-token — signed, httpOnly (auth token)
• teeny-pocket-ui-user-data — non-httpOnly (user info for the UI frontend)
• SameSite: Strict, Secure only on HTTPS

Scaffolds ​

Pre-built field and trigger definitions importable from teenybase/scaffolds/fields. These save boilerplate for common table patterns.

import { baseFields, authFields, createdTrigger, updatedTrigger } from 'teenybase/scaffolds/fields'

baseFields ​

Three fields every table should have: a unique ID, creation timestamp, and update timestamp.

authFields ​

Nine fields for user authentication. Add these alongside baseFields on your users table.

createdTrigger / updatedTrigger ​

SQL triggers for timestamp management. These are optional — they protect against raw SQL bypassing the API's built-in handling.

{
    triggers: [createdTrigger, updatedTrigger],
}

Indexes ​

Indexes improve query performance for frequently filtered or sorted columns.

{
    name: 'posts',
    fields: [/* ... */],
    indexes: [
        { fields: 'email', unique: true },           // Single column, unique
        { fields: ['status', 'created'] },            // Composite index
        { fields: 'category', where: { q: "status = 'active'" } },  // Partial index
    ],
}

Triggers ​

Custom SQL triggers that fire on table events. Use for data integrity rules, computed columns, or audit trails.

{
    triggers: [
        createdTrigger,                    // From scaffolds
        updatedTrigger,
        {
            name: 'set_deleted_at',
            seq: 'BEFORE',
            event: 'UPDATE',
            updateOf: 'deleted_by',
            body: sql`UPDATE files SET deleted_at = CURRENT_TIMESTAMP
                       WHERE id = NEW.id
                       AND OLD.deleted_by IS NULL
                       AND NEW.deleted_by IS NOT NULL`,
        },
    ],
}

Full-Text Search (FTS) ​

Built on SQLite FTS5. Enables fast text search across specified columns.

{
    name: 'posts',
    fields: [/* ... */],
    fullTextSearch: {
        fields: ['title', 'body'],
        tokenize: 'porter',
        contentless: true,
    },
}

Email Configuration ​

Required for password reset and email verification flows.

{
    email: {
        from: 'noreply@example.com',
        variables: {
            company_name: 'My App',
            company_url: 'https://myapp.com',
            company_address: '123 Main St',
            company_copyright: '© 2025 My App',
            support_email: 'support@myapp.com',
        },
        mock: false,

        // Choose one provider:
        mailgun: {
            MAILGUN_API_KEY: '$MAILGUN_API_KEY',
            MAILGUN_API_SERVER: 'api.eu.mailgun.net',
        },
        // — or —
        resend: {
            RESEND_API_KEY: '$RESEND_API_KEY',
        },
        // — or — (no API key; uses a Workers binding)
        cloudflare: {
            // binding: 'EMAIL',  // defaults to 'EMAIL'
        },
    },
}

Provider precedence is mailgun > resend > cloudflare — if more than one is configured, the first set wins.

Template Variables ​

You can add custom key-value pairs — they'll be available in email templates.

Mailgun Options ​

Resend Options ​

Cloudflare Options ​

Cloudflare Email Service uses a Workers binding instead of API keys. Before first use:

1. Onboard the sending domain: npx wrangler email sending enable yourdomain.com and follow the DNS-record prompts.

2. Declare the binding in wrangler.jsonc:

   jsonc

   {
     "send_email": [
       { "name": "EMAIL" }
       // For a dev guardrail, replace the entry above with the restricted form below
       // (don't add it as a second entry — two bindings with the same `name` collide):
       // { "name": "EMAIL", "allowed_destination_addresses": ["you@example.com"] }
     ]
   }

3. Set email.cloudflare in your teenybase config.

Notes:

• The Cloudflare binding has no inbound webhook surface; bounce/delivery telemetry would arrive via separate Email Routing handlers.
• Email tags from email.tags or per-send tags are silently dropped — the binding does not support them.

Plain-text body ​

Built-in templates (verification, password reset) produce both an html and a plain-text body. The plain text is rendered from paired text templates (*-text.ts) under src/worker/email/templates/, not stripped from html — this keeps the output clean for terminal clients, screen readers, and spam scoring.

Per-call override via the second argument to sendActionLink/sendActionText:

// html-only override (legacy form)
await email.sendActionLink({...}, '<table>...</table>')

// override both
await email.sendActionLink({...}, {
    html: '<table>...</table>',
    text: '{{message_title}}\n{{action_text}}: {{action_link}}',
})

Config-level override via emailTemplates.verification.layoutText / emailTemplates.passwordReset.layoutText (sibling to layoutHtml) on the auth extension config.

If you call email.sendEmail() directly, pass text alongside html.

Actions ​

Server-side logic callable via POST /api/v1/action/{name}. See the Actions Guide for full documentation with examples.

{
    actions: [
        {
            name: 'increment_counter',
            params: { amount: 'number' },
            requireAuth: true,
            sql: {
                type: 'UPDATE',
                table: 'counters',
                set: { value: 'value + {:amount}' },
                where: sql`id = 1`,
                returning: ['*'],
            },
        },
    ],
}

Auth Cookie ​

Configure cookie-based authentication. When set, teenybase will:

• Read the auth token from this cookie in initAuth() (on every request, after checking the Authorization header)
• Set the cookie automatically on OAuth redirect flows (Google One Tap, OAuth callback)
• Delete the cookie on logout

Note: JSON endpoints (login-password, sign-up, refresh-token) return the token in the response body but do not set a cookie. This is by design — setting Set-Cookie on JSON responses breaks CORS with wildcard origins, prevents CDN caching, and causes issues with mobile clients. For SSR routes in your worker, call the auth extension directly (for example, c.get('$db').table('users').extension('auth').loginWithPassword(...)) and set the cookie server-side with setCookie(...); do not same-origin fetch() your own auth endpoint just to set a cookie.

{
    authCookie: {
        name: 'auth_token',
        httpOnly: true,       // default: true — prevents JavaScript access
        secure: true,         // default: true — HTTPS only (set false for local dev)
        sameSite: 'Lax',      // default: 'Lax'
        path: '/',            // default: '/'
        maxAge: 604800,       // optional — cookie lifetime in seconds
        domain: '.example.com', // optional — defaults to current domain
    },
}

Auth Providers ​

Configure external authentication providers — OAuth redirect flows, JWT/Bearer token verification, or both. Use the unified authProviders array.

How it works:

• clientSecret present — OAuth redirect flow enabled (authorization code exchange)
• Known JWKS provider (e.g., 'google', 'supabase') or explicit jwksUrl/secret — Bearer token login enabled (via /auth/login-token)
• Both can be active on the same provider (e.g., Google supports OAuth redirect AND One Tap bearer tokens)

{
    authProviders: [
        // Google (both OAuth redirect + One Tap bearer)
        { name: 'google', clientId: '$GOOGLE_CLIENT_ID', clientSecret: '$GOOGLE_CLIENT_SECRET' },

        // GitHub (OAuth only)
        { name: 'github', clientId: '$GITHUB_CLIENT_ID', clientSecret: '$GITHUB_CLIENT_SECRET' },

        // Supabase (JWT only, JWKS auto-detected)
        { name: 'supabase', issuer: 'https://xyz.supabase.co/auth/v1' },

        // Custom issuer with HMAC secret
        { issuer: 'https://other.example.com', secret: '$OTHER_SECRET' },

        // JWKS URL (Auth0, Clerk, Okta, Keycloak, etc.)
        {
            issuer: 'https://myapp.auth0.com/',
            jwksUrl: 'https://myapp.auth0.com/.well-known/jwks.json',
            algorithm: 'RS256',
            clientId: '$AUTH0_CLIENT_ID',
        },

        // JWK public key object (RS256/ES256)
        {
            issuer: 'https://auth.myservice.com',
            secret: { kty: 'RSA', n: '...', e: 'AQAB' },
            algorithm: 'RS256',
            clientId: 'my-client-id',
        },

        // Custom OAuth provider (fully manual)
        {
            name: 'custom-provider',
            authorizeUrl: 'https://provider.com/oauth/authorize',
            tokenUrl: 'https://provider.com/oauth/token',
            userinfoUrl: 'https://provider.com/api/userinfo',
            clientId: '$CUSTOM_CLIENT_ID',
            clientSecret: '$CUSTOM_CLIENT_SECRET',
            scopes: ['openid', 'email'],
            mapping: { email: 'email_address', avatar: 'photo_url' },
        },

        // Partial mode: Bearer tokens set auth.email and auth.verified (for email-based rules)
        {
            issuer: 'https://internal-service.example.com',
            secret: '$INTERNAL_SERVICE_SECRET',
            bearerMode: 'partial',
        },

        // Cross-instance teenybase: full mode passes through user/session fields (uid, cid, sid, meta)
        {
            issuer: 'https://other-app.example.com',
            secret: '$OTHER_APP_JWT_SECRET',
            bearerMode: 'full',
        },

        // Admin mode: same as full + trusts the admin flag (only for fully trusted instances)
        {
            issuer: 'https://admin-app.example.com',
            secret: '$ADMIN_APP_JWT_SECRET',
            bearerMode: 'admin',
        },
    ],
}

Provider Properties ​

Field Mapping ​

mapping: {
    email: 'email',           // Default: 'email'
    name: 'name',             // Default: 'name'
    username: 'login',        // No default
    avatar: 'picture',        // No default
    verified: 'email_verified', // Default: 'email_verified'
}

The verified mapping reads a truthy/falsy flag from the provider response. Truthy (true / 1 / 'true') → user marked verified. Falsy → OAuth login rejected. Missing → falls back to trustEmailVerified (default false → rejected). See Email Verification Trust.

Two ways to provide the JWT verification key: ​

• secret — HMAC shared secret string ($ENV_VAR supported), PEM public key string, or JWK public key object
• jwksUrl — JWKS endpoint URL to auto-fetch and cache public keys (standard for Auth0, Clerk, Okta, etc.)

See the OAuth Guide for provider-specific setup instructions.

database ​

Selects the backend and carries connection info. Optional — omitting the field is equivalent to {type: 'd1-binding', binding: 'PRIMARY_DB'}.

Shape ​

Adapters ​

• d1-binding (built-in, zero-config default) — uses the wrangler D1 binding from the worker env.
• d1-rest (experimental) — talks to the Cloudflare D1 REST API. Requires the D1RestExtension to be imported and registered.
• libsql (experimental) — a libSQL server over HTTP. Requires the LibsqlExtension.
• d1-http (experimental) — a server exposing a D1-compatible HTTP API. Requires the D1HttpExtension.

The non-default adapter extensions (D1RestExtension, LibsqlExtension, D1HttpExtension) are exported from teenybase/worker and must be passed to db.registerExtension().

Example — d1-binding (default) ​

database: {type: 'd1-binding', binding: 'PRIMARY_DB'}

Example — libsql (experimental) ​

database: {type: 'libsql', url: '$LIBSQL_URL', authToken: '$LIBSQL_TOKEN'}

Example — d1-http (experimental) ​

database: {type: 'd1-http', url: '$SQLITE_URL', authToken: '$SQLITE_TOKEN'}

Example — d1-rest ​

database: {
    type: 'd1-rest',
    cloudflare: {
        accountId: '$CF_ACCOUNT_ID',
        databaseId: '$D1_DATABASE_ID',
        apiToken: '$CF_D1_EDIT_TOKEN',
    },
}

How JWT Signing Works ​

Teenybase uses a double-secret approach for table auth tokens. The actual signing key is the global jwtSecret concatenated with the table-level jwtSecret:

signing_key = global_jwtSecret + table_jwtSecret

This means:

• Changing the global secret invalidates all tokens across all tables
• Changing a table's secret only invalidates that table's tokens
• Both secrets must be present for table auth tokens to sign and verify correctly
• Tokens without a table claim (e.g. admin tokens) use only the global secret

// teenybase.ts
export default {
    jwtSecret: '$JWT_SECRET',           // global — part of every signing key
    tables: [{
        name: 'users',
        extensions: [{
            name: 'auth',
            jwtSecret: '$JWT_SECRET_USERS',  // table — combined with global
            // actual signing key = JWT_SECRET + JWT_SECRET_USERS
        }],
    }],
}

Use different $ENV_VAR names for the global and each table secret. This way, rotating one table's secret doesn't affect other tables.

Environment Variable Resolution ​

Any string value prefixed with $ is resolved from environment variables at runtime. This keeps secrets out of your config file.

jwtSecret: '$JWT_SECRET',    // Resolves to the value of JWT_SECRET env var

• Local dev: Read from .dev.vars file in your project root
• Production: Read from Cloudflare Worker secrets (upload via teeny secrets --remote --upload from .prod.vars)

Example .dev.vars:

JWT_SECRET=my-local-dev-secret-change-in-production
GOOGLE_CLIENT_ID=1234567890.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxx
MAILGUN_API_KEY=key-xxxxxxxx

Debug Flags (RESPOND_WITH_ERRORS, RESPOND_WITH_QUERY_LOG) ​

Two worker vars control how much detail an error response carries. Both are off unless set to "true" (or "1"). An unset var means off.

With both off, a failed request returns only code and message (plus field-level data for zod validation errors and for a taken email/username on sign-up). Generated SQL, bound values and internal error messages stay in the server log (teeny logs).

Even with both flags on, literal values written to password hash and salt columns, noSelect columns and password-type fields are rendered as '***' in data.input and queries (they are still bound to SQLite normally). Values computed by an SQL expression (for example set: {col: "lower('x')"}) are not redacted, so keep the flags off wherever real secrets are written.

Never enable either flag in production. teeny init writes "RESPOND_WITH_ERRORS": "false" into wrangler.jsonc. To see error details while developing locally, set it in .dev.vars, which only teeny dev / local mode reads and which overrides wrangler.jsonc vars:

# .dev.vars (local only)
RESPOND_WITH_ERRORS=true
RESPOND_WITH_QUERY_LOG=true

Upgrading from 0.0.x: RESPOND_WITH_ERRORS used to default to on when unset, and older scaffolds set it to "true" in wrangler.jsonc. Error responses also used to include the rendered SQL statement, including the password hash and salt on a failed sign-up. Set "RESPOND_WITH_ERRORS": "false" (or remove the var) in your wrangler.jsonc and move any "true" into .dev.vars.

Observability (wrangler.jsonc) ​

The observability block in wrangler.jsonc enables Cloudflare Workers Logs — stored for 7 days on paid plans, 3 days on free. Generated by teeny init with sensible defaults:

"observability": {
    "enabled": true,
    "logs": {
        "invocation_logs": true,
        "head_sampling_rate": 1
    }
}

Stream logs via teeny logs (needs CLOUDFLARE_API_TOKEN, not just wrangler login) — see CLI Reference.

Note: This is a wrangler.jsonc setting, not a teenybase.ts setting. It controls Cloudflare platform-level logging, not application-level config.

Back to README | Actions Guide | API Endpoints | Getting Started