Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

kamaal-auth

Shared auth stack for multiple apps, so an improvement lands once instead of twice.

One repo, three published artifacts:

Artifact Name Consumed as
npm package @kamaalio/kamaal-auth-core (in packages/core/) the auth engine, with no server library of its own
npm package @kamaalio/kamaal-auth-hono (in packages/hono/) a mountable Hono auth router
Swift package KamaalAuth (at the repo root) KamaalAuth

The two npm packages release in lockstep under the same semver tag used by SwiftPM.

Why the split

kamaal-auth-core holds everything worth sharing: the hook contract, session resolution and JWT verification, the credential-header wire format, error-to-status mapping and the OpenAPI schemas. It expresses every operation against a plain Request, so it has no opinion about how requests reach it.

kamaal-auth-hono is the adapter: route definitions, a session middleware, and the translation between a Hono Context and the engine. Supporting another server library means writing another adapter of about that size, not another auth package.

A Hono app depends on kamaal-auth-hono alone — it re-exports everything kamaal-auth-core exports, so there is one package to add and one package to import from. Add kamaal-auth-core directly only if you are writing a new adapter, or using the engine without a server library at all.

Two things this package deliberately does not own

It does not own your database schema. Your app defines and migrates its own user / session / account / verification / jwks tables and keeps them fully visible. Nothing here reads or writes them.

It does not make requests, or accept a better-auth instance. You supply hook functions implementing the auth operations, and the package derives its types from those signatures. better-auth, drizzle-orm, and your database driver never enter this package's dependency graph — which is why two apps on different better-auth versions can share it.

kamaal-auth-core's only peer dependency is jose. It ships its own default request/response schemas, built with Zod internally, but every schema-accepting option (payloadSchemas, errorSchemas, sessionExtras) takes any Standard Schema — Zod, ArkType, Valibot, or your own — so a consumer never has to install Zod. kamaal-auth-hono adds hono and @kamaalio/hono-standard-openapi as peers on top of the core package.

Server usage

import { createAuthModule, defineAuthHooks } from '@kamaalio/kamaal-auth-hono';

const hooks = defineAuthHooks({
  async signIn(c, input) {
    /* call your better-auth instance, return { ok: true, value: { user, credentials } } */
  },
  async signUp(c, input) {
    /* … */
  },
  async signOut(c) {
    /* … */
  },
  async getSession(c) {
    /* … */
  },
  async issueToken(c) {
    /* … */
  },
  async jwks(c) {
    /* … */
  },
});

const auth = createAuthModule({
  hooks,
  config: {
    basePath: '/app-api/auth',
    trustedOrigins: ['myapp://'],
    session: { expiresInSeconds: THIRTY_DAYS, updateAgeSeconds: ONE_DAY },
    jwt: { issuer, audience, expiresInSeconds: SEVEN_DAYS, jwksUrl },
  },
});

app.route('/app-api/auth', auth.router);

Apps with extra per-user state extend the session response without the package knowing what it is:

sessionExtras: {
  schema: z.object({ preferred_currency: CurrencyShape, has_preferred_currency_preference: z.boolean() }),
  resolve: async (c, { userId }) => ({ /* … */ }),
},
extraRoutes: (router, deps) => router.openapi(preferencesRoute(deps.schemas.SessionResponseSchema), handler),

Provider failures and credential safety

All hook failures, including getSession and issueToken, use config.errorStatuses. SESSION_NOT_FOUND defaults to 401; unknown codes default to 500. Return a successful getSession result containing null only when the session is actually missing. A database outage or signing-key failure should return a failure with its own code instead:

return { ok: false, error: { code: 'TOKEN_ISSUANCE_FAILED', message: 'Authentication temporarily unavailable' } };

Map any provider-specific session rejection codes to 401 through errorStatuses. The Hono OpenAPI routes document 500 responses so generated clients can handle them. Native request hooks must preserve the HTTP status when constructing AuthRequestFailure; the Swift client keeps stored credentials on server failures and clears them on authentication rejection. Consumers upgrading from versions that converted every lookup or refresh failure to 401 should check their provider's rejection codes and add these mappings explicitly.

Hook error messages are returned to clients, so keep them safe and generic. The package's failure logs include only event, error code, credential kind, and status, never upstream messages or credential values. Consumer HTTP logging should omit authentication request and response bodies, authorization headers, cookies, and auth query parameters: those can contain passwords, email addresses, or tokens. Signing-key storage and recovery remain app-owned.

Releasing

All artifacts use one version line. GitHub Actions publishes the npm packages after a bare semver tag (<version>) is pushed, and SwiftPM resolves that same tag directly from the repository.

To release all packages, create and push one tag:

git tag <version>
git push origin <version>

Development

just            # list commands
just prepare    # install modules
just ready      # quality + tests, both languages

Swift usage

Same idea as the server: you supply the requests, the package supplies everything worth sharing. import KamaalAuth is the only import an app needs — it re-exports the credential storage layer, the networking client, the OpenAPI middleware, and the SwiftUI screens as one module. Test targets additionally import KamaalAuthTestSupport for MockAuthRequestHooks.

Implement AuthRequestHooks with your own generated client, and the client layer owns credential storage, the refresh policy, expiry rules, session modelling and error semantics.

struct MyAuthHooks: AuthRequestHooks {
    let client: Client  // your generated OpenAPI client

    func signIn(_ payload: SignInPayload) async -> AuthRequestOutcome<AuthCredentialHeaders> {
        // call your client, then hand the response headers over
        guard let headers = AuthCredentialHeaders(headers: response.headers) else {
            return .failure(AuthRequestFailure(status: 500))
        }
        return .success(headers)
    }
    // signUp, signOut, session, issueToken likewise
}

let auth = KamaalAuthClientImpl(hooks: MyAuthHooks(client: client), credentialsKey: "\(bundleID).credentials")

KamaalAuthUI provides the shared sign-in/sign-up flow and gates app content until authentication completes:

@State private var auth = KamaalAuth(
    client: client,
    configuration: KamaalAuthConfiguration(appName: "My App")
)

Text("Signed in")
    .kamaalAuth(auth)

Because the requests live in your app, this package has no HTTP stack, no transport, and no knowledge of your code generation. Its only dependency is KamaalSwift.

AuthErrorBody.failure(status:body:) turns an error response into an AuthRequestFailure, including the field-level validations, so each app does not re-derive the envelope.

To authenticate your app's other requests, ask for a token that is guaranteed fresh — it refreshes first when the stored one is stale or nearly expired:

if let token = await auth.validAuthToken() {
    request.headerFields[.authorization] = "Bearer \(token)"
}

App-specific user fields ride along untouched. Anything the package does not model is preserved on AuthSession.extras:

let currency = session.extras["preferred_currency"]?.stringValue
let preferences = try session.decodeExtras(as: Preferences.self)

Credentials stored in an older shape fail to decode, which reads as signed out. Adopting this package costs each app one forced re-login.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂