@useoneauth/adapter-sdk

The contract for building OneAuth adapters. OneAuth owns ports, not integrations — it ships these port interfaces plus a conformance kit, and the ecosystem builds the integrations (Postgres, Redis, Mongo, Drizzle, Prisma, AWS, …). In-memory is the canonical reference adapter.

What an adapter is

An adapter implements OneAuth's storage ports — and nothing else. It owns no policy, no trust logic, no lifecycle rules; those live in the runtime. An adapter is pure persistence behind a well-defined interface.

import type { Adapters, SessionRepository } from "@useoneauth/adapter-sdk"

export class MySessionRepository implements SessionRepository {
  // create / findById / findByIdentity / list / update
}

The full set of ports is the Adapters interface: identity, relationship, membership, organization, credential, credentialVersion, credentialPolicy, session, refreshToken, keyStore, eventStore.

Prove it with the conformance kit

Every adapter must pass the same conformance suite the in-memory reference passes. Each suite is parameterized by a factory:

import { describe } from "vitest"
import { testSessionRepository, testEventStore } from "@useoneauth/adapter-sdk/conformance"
import { MySessionRepository } from "../src/MySessionRepository.js"
import { MyEventStore } from "../src/MyEventStore.js"

testSessionRepository(() => new MySessionRepository())
testEventStore(() => new MyEventStore())

The kit enforces the contracts that the runtime depends on, e.g.:

• EventStore — monotonic sequence, duplicate-id rejection, immutable (frozen) stored events. The event stream is replayable and load-bearing.
• RelationshipRepository — findByFrom / findByTo, which the identity graph uses for cycle detection.
• SessionRepository — list() (fleet-wide), findByIdentity, and the optional organizationId scope used by org-leave revocation.

Secrets-at-rest expectations

Adapters persist hashes only — never plaintext credentials or tokens. The runtime hashes before handing data to your adapter (with an optional application pepper), and the event stream is redacted before persistence, so a faithfully-implemented adapter never stores a raw secret. For key material, prefer the runtime's EncryptedKeyStore (AES-256-GCM + a terminal-entered password) or a cloud-KMS KeyStore adapter.

Checklist

1. Implement the port(s) you need from @useoneauth/adapter-sdk.
2. Run the matching conformance suite(s) — all green.
3. Persist hashes only; never log or store raw secrets.
4. Publish; wire it via createOneAuth({ adapters: { … } }) (composition root).

Currently published suites: testEventStore, testIdentityRepository, testRelationshipRepository, testSessionRepository. The remaining ports follow the same factory pattern and are being added incrementally.