Forge Integration

Keysmith ships with a Forge extension adapter that handles DI registration, REST API route mounting, and database migration on startup.

Mounting the extension

import (
    "github.com/xraph/forge"
    "github.com/xraph/keysmith"
    "github.com/xraph/keysmith/extension"
    "github.com/xraph/keysmith/store/postgres"
    audithook "github.com/xraph/keysmith/audit_hook"
)

app := forge.New(
    forge.WithExtension(
        extension.New(
            extension.WithEngineOptions(
                keysmith.WithStore(pgStore),
            ),
            extension.WithHookExtension(audithook.New(recorder)),
        ),
    ),
)

What the extension does

On registration

1. Registers keysmith.Engine in the Forge DI container via vessel.Provide
2. Registers the API route handler

On start

1. Runs database migrations if a PostgreSQL store is configured
2. Starts any background processes (e.g., expired key cleanup)

On stop

1. Fires the Shutdown plugin hook
2. Closes the store connection

REST API routes

When mounted, the extension exposes the full Keysmith REST API:

Automatic tenant scoping

When running inside Forge, Keysmith automatically extracts the app ID and tenant ID from forge.Scope. No manual WithTenant call is needed.

DI integration

Access the engine from the Forge DI container:

// In a Forge handler
func myHandler(ctx forge.Context) error {
    eng := vessel.MustResolve[*keysmith.Engine](ctx.Vessel())
    // use eng...
}

Grove database integration

When your Forge app uses the Grove extension to manage database connections, Keysmith can automatically resolve a grove.DB from the DI container and construct the correct store backend based on the driver type.

Using the default grove database

If the Grove extension registers a single database (or a default in multi-DB mode), use WithGroveDatabase with an empty name:

ext := extension.New(
    extension.WithGroveDatabase(""),
)

Using a named grove database

In multi-database setups, reference a specific database by name:

ext := extension.New(
    extension.WithGroveDatabase("keysmith"),
)

This resolves the grove.DB named "keysmith" from the DI container and auto-constructs the matching store. The driver type is detected automatically -- you do not need to import individual store packages.

Store resolution order

The extension resolves its store in this order:

1. Explicit store -- if WithEngineOptions(keysmith.WithStore(s)) was called, it is used directly and grove is ignored.
2. Grove database -- if WithGroveDatabase(name) was called, the named or default grove.DB is resolved from DI.
3. In-memory fallback -- if neither is configured, an in-memory store is used.

Extension options

File-based configuration (YAML)

When running as a Forge extension, Keysmith automatically loads configuration from YAML config files. The extension looks for config under the following keys (in order):

1. extensions.keysmith -- standard Forge extension config namespace
2. keysmith -- top-level shorthand

Example

# forge.yaml
extensions:
  keysmith:
    disable_routes: false
    disable_migrate: false
    base_path: "/keysmith"
    grove_database: ""

Config fields

Merge behaviour

File-based configuration is merged with programmatic options. Programmatic boolean flags (DisableRoutes, DisableMigrate) always win when set to true. For other fields, YAML values take precedence, then programmatic values, then defaults.