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.
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.
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.
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),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.
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>just # list commands
just prepare # install modules
just ready # quality + tests, both languagesSame 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.