@datar-platform/better-auth-dynamodb 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @datar-platform/better-auth-dynamodb
 
+## 0.2.0
+
+### Breaking
+
+- **The physical key format changed.** Every variable component of a key is now
+  written length-prefixed (`s<byteLength>:<value>`) and type-tagged, and a
+  value longer than 256 bytes is SHA-256 hashed into the key. Existing tables
+  written by 0.1.x will not be found by 0.2.0 and must be recreated. See
+  "Delimiter safety" below for why this was worth a break.
+- **Queries no index can serve now throw** instead of silently reading every
+  row of the model and filtering in memory. Set `unsafeAllowScan: true` to
+  restore the old behaviour, or give the field an index (`unique`,
+  `references`, or `index: true` in the Better Auth schema). Native `count` is
+  unaffected — it is a keyed `Select: COUNT` query, not a scan.
+- **`create` no longer overwrites.** `put` is conditional on the row not
+  already existing, so a colliding id fails loudly rather than replacing data.
+- **Peer range raised to `better-auth >= 1.7.0`**, which is what the adapter is
+  now built and conformance-tested against.
+- Draining is capped at `maxPages` (default 25). A query with pages remaining
+  at the cap throws rather than returning a partial result — silently dropping
+  rows from an auth query is worse than failing.
+
+### Added
+
+- **Atomic uniqueness.** `unique` schema fields (`user.email`, `session.token`,
+  `organization.slug`, …) are enforced by DynamoDB itself, via marker rows
+  written in the same `TransactWriteItems` as the row they describe. Better
+  Auth's own enforcement is a check-then-insert, which two concurrent sign-ups
+  can both pass. Opt out with `atomicUniqueness: false`.
+  - Note for existing tables: markers are only created by writes made on
+    0.2.0+. Uniqueness is enforced going forward; pre-existing duplicates are
+    not detected retroactively.
+- **Optimistic concurrency.** Every row carries a hidden revision that guards
+  `update`, `delete`, `consumeOne`, and `incrementOne`. A write that lost a
+  race retries against the fresh row, then fails with `OptimisticLockError`
+  rather than silently clobbering a concurrent change. Rows written before
+  0.2.0 are matched on the revision being absent, so they migrate in place on
+  first write.
+- **Adapter-managed TTL** (`ttl: { defaultField: "expiresAt" }`). The
+  configured date field is projected into a DynamoDB TTL attribute so expired
+  sessions and verifications are reaped for free, and the same attribute is
+  treated as _logical_ expiry on read — DynamoDB reaps lazily, so without that
+  an expired session would keep working until AWS got round to it.
+  `ensureSchema`/`generateSchemaFile` provision the TTL setting.
+- **Client injection.** `documentClient` on the adapter config, so your
+  application owns credentials, region, middleware, tracing, and marshalling.
+- `pageSize` for per-request `Limit` tuning.
+- Typed errors, all exported and all extending `DynamoDBAdapterError`:
+  `UniqueConstraintError`, `OptimisticLockError`, `UnsupportedQueryError`.
+
+### Fixed
+
+- **Delimiter safety.** Keys were joined with a bare `#`, so a value containing
+  the delimiter could forge another key: with a composite partition key,
+  `("a#b", "c")` and `("a", "b#c")` encoded identically, and a sort-key
+  `begins_with("cred#")` probe matched a row whose value was literally
+  `cred#ential`. Auth tables hold plenty of values that arrive from outside —
+  OAuth `accountId`s, organisation slugs, verification identifiers — so this is
+  now structurally impossible rather than merely unlikely.
+- **Oversized key values** produced an opaque DynamoDB `ValidationException`.
+  Long values are hashed; an overflow can now only come from an absurd model,
+  index, or id name, and says so.
+- **Cancelled transactions were all read as uniqueness violations.** DynamoDB
+  cancels for throttling, item contention, and validation failures too, so a
+  throttled write could be reported to a user as "that email is taken".
+  Cancellations are now classified by their per-action code; contention is
+  retried, and only a genuine `ConditionalCheckFailed` becomes
+  `UniqueConstraintError`.
+- **`incrementOne` could create the row it was told to increment.** DynamoDB's
+  `ADD` is an upsert; the write is now conditional on the row existing and
+  returns `null` when it does not.
+- **`incrementOne` left stale index rows** when its `set` moved an indexed or
+  TTL field, because a native `ADD` cannot re-encode GSI keys. Those cases now
+  take the read-modify-write path.
+- **A `where` naming `id` alongside other predicates ignored the others**, so a
+  guarded `update`/`delete` could fire against a row that did not qualify.
+- **`select` was ignored** by `findOne`/`findMany`, and needed mapping through
+  the schema's `fieldName` overrides.
+- **`id in [...]` fell through to a model scan.** Better Auth batch-loads rows
+  it already has ids for (an organisation's members, for one), which DynamoDB
+  serves as a bounded multi-get. It is now planned as one.
+- **`count` used the native fast path for id lookups**, which counts a whole
+  model or index — answering "how many of these three ids exist" with the size
+  of the table.
+- **Case-insensitive equality was served from an index**, which byte-compares
+  keys and so missed every row whose casing differed. Those clauses are now
+  matched in memory.
+
+### Testing
+
+- Better Auth's **official adapter conformance suites** (`normal`, `uuid`,
+  `caseInsensitive`, `authFlow`) now run against real DynamoDB. They found four
+  of the bugs listed above.
+- The e2e suite moved from LocalStack + docker-compose to AWS's own DynamoDB
+  Local, started per-run by Testcontainers — nothing to start by hand, no port
+  collisions, no container surviving a crashed run.
+- New unit suites cover key-collision resistance, transaction-cancellation
+  classification, the page cap, the scan guard, and the store's write paths
+  against an in-memory DynamoDB double.
+
 ## 0.1.1
 
 ### Patch Changes
@@ -10,7 +110,7 @@
   used by the email-OTP verify flow — and `incrementOne` for atomic guarded
   counter updates. Without them, any consumer on better-auth >=1.7 hit
   `BetterAuthError: Adapter "dynamodb" must implement consumeOne for atomic
-  single-use credential consumption` the first time a plugin exercised that
+single-use credential consumption` the first time a plugin exercised that
   path (e.g. `emailOTP().signIn`).
 - `consumeOne` is implemented on the built-in store as a native
   `DeleteCommand` with `ReturnValues: "ALL_OLD"` (atomic delete-and-return);

package/README.md

@@ -8,7 +8,16 @@ A generic [DynamoDB](https://aws.amazon.com/dynamodb/) adapter for [Better Auth]
 - **Bring your own store.** The adapter talks to a small `DynamoStore` seam, so
   you can back it with an existing single-table design (ElectroDB, custom key
   encoding, a shared table) without changing the adapter.
-- **Correct pagination.** `findMany`/`count` drain every page — no silent row cap.
+- **Atomic uniqueness.** `unique` fields are enforced by DynamoDB itself, in the
+  same transaction as the row — not by a check-then-insert two concurrent
+  sign-ups can both pass.
+- **Safe under concurrency.** Every row carries a revision that guards updates,
+  deletes, and single-use consumes against lost writes.
+- **No hidden scans, no silent truncation.** A query no index can serve fails
+  loudly instead of quietly reading the whole model, and pagination that hits
+  its cap throws rather than returning part of an answer.
+- **Passes Better Auth's official adapter conformance suites** against real
+  DynamoDB.
 - Zero dependencies beyond the AWS SDK.
 
 ## Install
@@ -58,6 +67,43 @@ You can also generate a CloudFormation template via the Better Auth CLI
 (`npx @better-auth/cli generate`) — the adapter's `createSchema` emits one sized
 to your access patterns.
 
+### Expiring sessions and verifications
+
+Nothing expires on its own. Point the adapter at your expiry field and DynamoDB
+reaps expired rows for free:
+
+```ts
+dynamoAdapter({
+  tableName: "better-auth",
+  ttl: { defaultField: "expiresAt" },
+});
+```
+
+Pass the same attribute to `ensureSchema({ ..., ttlAttribute: "__ba_ttl" })` —
+the adapter writes the attribute, but only the table setting makes AWS act on
+it. Reads treat it as _logical_ expiry too: DynamoDB reaps lazily, often a day
+or two late, so without that an expired session would keep working until AWS got
+round to deleting it.
+
+### Uniqueness
+
+Fields the Better Auth schema marks `unique` — `user.email`, `session.token`,
+`organization.slug` — get a marker row written in the same
+`TransactWriteItems` as the row itself, conditional on the marker not already
+existing. That makes uniqueness a property of the database: of two concurrent
+sign-ups for the same email, exactly one commits.
+
+Better Auth's own enforcement is a check-then-insert, which both racers can
+pass. Set `atomicUniqueness: false` to fall back to it and halve the write cost
+of creates.
+
+Two caveats worth knowing:
+
+- Markers are created by writes made on 0.2.0+. Upgrading an existing table
+  enforces uniqueness going forward; it does not find duplicates already there.
+- Do not write Better Auth rows into the table with a raw `PutItem`. Entity
+  rows, index keys, markers, and TTL attributes have to move together.
+
 ## Bring your own store
 
 Implement `DynamoStore` to run the same adapter against your own table layout.
@@ -114,23 +160,42 @@ omit it to auto-derive from the schema.
 
 ## Configuration
 
-| Option      | Default                               | Description                                                                                       |
-| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `store`     | built-in single-table store           | Storage backend (`DynamoStore`).                                                                  |
-| `indexMap`  | derived from schema                   | Access-pattern map.                                                                               |
-| `tableName` | `DYNAMODB_TABLE_NAME` → `better-auth` | Table name (built-in store).                                                                      |
-| `region`    | SDK default                           | AWS region (built-in store).                                                                      |
-| `endpoint`  | SDK default                           | Endpoint override for DynamoDB Local / LocalStack, e.g. `http://localhost:4566` (built-in store). |
-| `debugLogs` | `false`                               | Better Auth debug logging.                                                                        |
+| Option             | Default                               | Description                                                                                                                 |
+| ------------------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `store`            | built-in single-table store           | Storage backend (`DynamoStore`).                                                                                            |
+| `indexMap`         | derived from schema                   | Access-pattern map.                                                                                                         |
+| `tableName`        | `DYNAMODB_TABLE_NAME` → `better-auth` | Table name (built-in store).                                                                                                |
+| `region`           | SDK default                           | AWS region (built-in store).                                                                                                |
+| `endpoint`         | SDK default                           | Endpoint override for DynamoDB Local / LocalStack, e.g. `http://localhost:8000` (built-in store).                           |
+| `documentClient`   | created internally                    | Pre-built `DynamoDBDocumentClient`. Preferred in production, so your app owns credentials, region, middleware, and tracing. |
+| `atomicUniqueness` | `true`                                | Enforce `unique` fields with transactional marker rows.                                                                     |
+| `ttl`              | disabled                              | Adapter-managed DynamoDB TTL, e.g. `{ defaultField: "expiresAt" }`.                                                         |
+| `maxPages`         | `25`                                  | Cap on pages drained per query. Throws at the cap rather than returning a partial result.                                   |
+| `pageSize`         | SDK default                           | Per-request DynamoDB `Limit`. Changes request sizing only, not logical results.                                             |
+| `unsafeAllowScan`  | `false`                               | Allow queries no index can serve, which read every row of the model and filter in memory.                                   |
+| `debugLogs`        | `false`                               | Better Auth debug logging.                                                                                                  |
 
 ## Notes & limitations
 
 - IDs are strings (Better Auth generates them); `supportsNumericIds` is `false`.
 - Dates are stored as ISO strings and re-hydrated on read (`supportsDates: false`).
-- No native transactions — multi-row ops run sequentially in small batches.
+- No interactive transactions — DynamoDB has no such API, so the adapter
+  reports `transaction: false`. `TransactWriteItems` is used internally for
+  single-row atomic operations; multi-row ops run sequentially in small batches.
+- Case-insensitive equality (`mode: "insensitive"`) cannot come from an index,
+  because DynamoDB compares keys byte-for-byte. Those clauses are matched in
+  memory, so they need `unsafeAllowScan: true` unless another clause in the same
+  `where` can be served by an index.
+- Better Auth's verification cleanup issues a range-only
+  `deleteMany(expiresAt < now)`, which has no key to work from. Configure `ttl`
+  and set `verification: { disableCleanup: true }` — that is the
+  DynamoDB-shaped answer to the same problem.
 - The built-in store's derived index map keys on schema field names; custom
   `fieldName` mappings are not yet resolved in derivation (pass an explicit
   `indexMap` if you rename fields).
+- Key values longer than 256 bytes are SHA-256 hashed into the key. Lookups are
+  unaffected — both sides hash identically — but a key is no longer always
+  readable as plain text when debugging.
 
 ## License
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { BetterAuthOptions } from 'better-auth';
 import { AdapterFactory } from 'better-auth/adapters';
-import { DBAdapterDebugLogOption, CleanedWhere } from '@better-auth/core/db/adapter';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { DBAdapterDebugLogOption, CleanedWhere } from '@better-auth/core/db/adapter';
 import { BetterAuthDBSchema } from '@better-auth/core/db';
 import { CreateTableCommandInput, DynamoDBClient } from '@aws-sdk/client-dynamodb';
 
@@ -29,6 +29,14 @@ interface AccessPattern {
      * (as `eq` clauses), and leaves the rest to residual in-memory filtering.
      */
     sk?: string[];
+    /**
+     * True when this pattern backs a *uniqueness constraint* (a schema field
+     * marked `unique`, e.g. `user.email`) rather than a plain lookup. The
+     * built-in store enforces these atomically with marker rows; a custom store
+     * may ignore the flag and fall back to Better Auth's application-layer
+     * check-then-insert.
+     */
+    unique?: boolean;
 }
 /** Ordered list of access patterns for a single model, most specific first. */
 type ModelIndexMap = AccessPattern[];
@@ -129,6 +137,25 @@ interface DynamoStore {
         overwrite?: boolean;
     }>;
 }
+/**
+ * Adapter-managed DynamoDB TTL.
+ *
+ * A configured date field (e.g. `session.expiresAt`) is projected into a
+ * numeric epoch-seconds attribute that DynamoDB's own TTL reaper understands,
+ * so expired auth rows are deleted for free instead of accumulating.
+ *
+ * Reads treat the same attribute as *logical* expiry. DynamoDB reaps lazily —
+ * often a day or two late — so without that, an expired session would keep
+ * working until AWS got round to deleting it.
+ */
+interface TtlOptions {
+    /** DynamoDB TTL attribute to write. Defaults to `__ba_ttl`. */
+    attributeName?: string;
+    /** Per-model date field, e.g. `{ session: "expiresAt" }`. */
+    fields?: Record<string, string>;
+    /** Date field used for any model not named in `fields`, e.g. `"expiresAt"`. */
+    defaultField?: string;
+}
 /**
  * Public configuration for {@link dynamoAdapter}.
  *
@@ -150,6 +177,41 @@ interface DynamoAdapterConfig {
      * at DynamoDB Local or LocalStack, e.g. `http://localhost:4566`.
      */
     endpoint?: string;
+    /**
+     * Pre-built DynamoDB document client (used only by the built-in store).
+     * Preferred in production: your application keeps ownership of credentials,
+     * region, middleware, tracing, and marshalling behaviour.
+     */
+    documentClient?: DynamoDBDocumentClient;
+    /**
+     * Enforce `unique` schema fields with transactional marker rows (used only
+     * by the built-in store). Default `true`.
+     */
+    atomicUniqueness?: boolean;
+    /**
+     * Maximum DynamoDB pages drained for one logical query. Default 25. When a
+     * query still has pages left at the cap, the adapter throws rather than
+     * returning a silently truncated result — a partial answer to an auth query
+     * is worse than a loud failure.
+     */
+    maxPages?: number;
+    /**
+     * Per-request DynamoDB `Limit` (used only by the built-in store). Pagination
+     * is still drained up to `maxPages`, so this changes request sizing only.
+     */
+    pageSize?: number;
+    /** Adapter-managed DynamoDB TTL. Omit (or `false`) to disable entirely. */
+    ttl?: TtlOptions | false;
+    /**
+     * Allow queries that no index can serve, which fall back to draining every
+     * row of the model and filtering in memory. Default `false`, so an access
+     * pattern nobody designed for fails at development time instead of quietly
+     * costing a full model read on every call.
+     *
+     * Native `count` is unaffected: it is a keyed `Select: COUNT` query, bounded
+     * by `maxPages`, and returns a number rather than every row.
+     */
+    unsafeAllowScan?: boolean;
     /** Better Auth debug logging, forwarded to the adapter factory. */
     debugLogs?: DBAdapterDebugLogOption;
 }
@@ -170,11 +232,67 @@ interface DynamoAdapterConfig {
  */
 declare const dynamoAdapter: (config?: DynamoAdapterConfig) => AdapterFactory<BetterAuthOptions>;
 
+/**
+ * Error types raised by this adapter.
+ *
+ * Everything thrown from the adapter core or the built-in store derives from
+ * {@link DynamoDBAdapterError}, so a consumer can distinguish "the adapter
+ * refused/failed" from a raw AWS SDK error escaping the seam.
+ */
+declare class DynamoDBAdapterError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A write lost a race against a uniqueness constraint — another row already
+ * holds the value for a `unique` field (e.g. `user.email`, `organization.slug`).
+ */
+declare class UniqueConstraintError extends DynamoDBAdapterError {
+    readonly model: string;
+    readonly fields: string[];
+    constructor(model: string, fields: string[], options?: ErrorOptions);
+}
+/**
+ * The requested access pattern cannot be served without a table/model scan, and
+ * scans have not been explicitly enabled.
+ */
+declare class UnsupportedQueryError extends DynamoDBAdapterError {
+    constructor(message: string);
+}
+/**
+ * A guarded write was rejected because the row changed between the adapter's
+ * read and its write. Better Auth's own retry/null semantics decide what
+ * happens next; this exists so the cause is legible rather than an opaque
+ * `TransactionCanceledException`.
+ */
+declare class OptimisticLockError extends DynamoDBAdapterError {
+    constructor(model: string, id: string, options?: ErrorOptions);
+}
+/** True for a bare `ConditionalCheckFailedException` from a non-transactional write. */
+declare const isConditionalCheckFailed: (error: unknown) => boolean;
+/** True for any cancelled `TransactWriteItems`, whatever the reason. */
+declare const isTransactionCanceled: (error: unknown) => boolean;
+/**
+ * The per-action cancellation codes AWS attaches to a cancelled transaction
+ * (e.g. `ConditionalCheckFailed`, `TransactionConflict`, `ThrottlingError`,
+ * `ValidationError`, or `None` for actions that were fine).
+ */
+declare function transactionCancellationCodes(error: unknown): string[];
+/**
+ * True only when a transaction was cancelled *because a condition failed* —
+ * not because of throttling, a transaction conflict, or a validation error.
+ *
+ * This distinction matters: reporting a throttled write as "email already
+ * taken" is a user-visible lie, and it is the failure mode of any code that
+ * treats `TransactionCanceledException` as a uniqueness violation wholesale.
+ */
+declare const isConditionalTransactionCanceled: (error: unknown) => boolean;
+
 /**
  * A resolved query plan: how the adapter will fetch candidate rows for a
  * `where` clause before applying any residual (in-memory) filtering.
  *
  * - `byId`      — a direct primary-key get (the cheapest path).
+ * - `byIds`     — a bounded set of primary-key gets (`id in [...]`).
  * - `index`     — a logical index query with a resolved partition/sort key.
  * - `listByType`— no index matched; list all rows of the model and filter.
  *
@@ -185,6 +303,10 @@ type QueryPlan = {
     kind: "byId";
     id: string;
     residual: CleanedWhere[];
+} | {
+    kind: "byIds";
+    ids: string[];
+    residual: CleanedWhere[];
 } | {
     kind: "index";
     index: string;
@@ -219,8 +341,24 @@ interface SingleTableStoreOptions {
     endpoint?: string;
     /** Resolved logical access-pattern map (derived or user-supplied). */
     indexMap: IndexMap;
-    /** Pre-built document client (used by tests, e.g. against DynamoDB Local). */
+    /**
+     * Pre-built document client. Preferred in production, so your application
+     * owns credentials, region, middleware, tracing, and marshalling.
+     */
     documentClient?: DynamoDBDocumentClient;
+    /**
+     * Enforce `unique` schema fields with transactional marker rows. Default
+     * `true`. Turning it off halves the write cost of creates and restores
+     * Better Auth's application-layer check-then-insert, which can admit
+     * duplicates under concurrency.
+     */
+    atomicUniqueness?: boolean;
+    /** Max DynamoDB pages drained for one internal count. Default 25. */
+    maxPages?: number;
+    /** Optional per-request DynamoDB `Limit`. Does not change logical results. */
+    pageSize?: number;
+    /** Adapter-managed DynamoDB TTL. Omit (or `false`) to disable entirely. */
+    ttl?: TtlOptions | false;
 }
 /**
  * A zero-dependency (beyond the AWS SDK) DynamoDB store for Better Auth.
@@ -230,6 +368,10 @@ interface SingleTableStoreOptions {
  * through logical index names only. Works with any Better Auth model or plugin
  * whose looked-up fields are described by the (typically schema-derived) index
  * map.
+ *
+ * Every mutation is guarded: creates are conditional on the row not already
+ * existing, updates and deletes carry an optimistic revision check, and
+ * uniqueness markers move in the same transaction as the row they describe.
  */
 declare function createSingleTableStore(opts: SingleTableStoreOptions): DynamoStore;
 
@@ -257,6 +399,12 @@ declare function ensureSchema(opts: {
     client: DynamoDBClient;
     tableName: string;
     lookupSlots: number;
+    /**
+     * Enable DynamoDB TTL on this attribute. Pass the same value the adapter is
+     * configured with (`ttl.attributeName`, default `__ba_ttl`) — the adapter
+     * writes the attribute, but only the table setting makes AWS act on it.
+     */
+    ttlAttribute?: string;
 }): Promise<void>;
 /**
  * Better Auth CLI `generate` hook: emit a portable CloudFormation template for
@@ -268,12 +416,16 @@ declare function generateSchemaFile(opts: {
     tableName: string;
     lookupSlots: number;
     file?: string;
+    /** When set, the template enables DynamoDB TTL on this attribute. */
+    ttlAttribute?: string;
 }): {
     code: string;
     path: string;
     overwrite: boolean;
 };
 
+/** Default DynamoDB TTL attribute (epoch seconds). Configurable per store. */
+declare const DEFAULT_TTL_ATTRIBUTE = "__ba_ttl";
 /** Physical slot assignment: model -> (logical index name -> GSI slot number). */
 interface SlotAssignment {
     slots: Record<string, Record<string, number>>;
@@ -286,4 +438,4 @@ interface SlotAssignment {
  */
 declare function assignSlots(indexMap: IndexMap): SlotAssignment;
 
-export { type AccessPattern, type DynamoAdapterConfig, type DynamoStore, type IndexMap, type ModelIndexMap, type QueryPage, type QueryPlan, type SingleTableStoreOptions, type StoreItem, assignSlots, buildTableDefinition, createSingleTableStore, deriveIndexMap, dynamoAdapter, ensureSchema, generateSchemaFile, matchesResidual, planQuery };
+export { type AccessPattern, DEFAULT_TTL_ATTRIBUTE, type DynamoAdapterConfig, DynamoDBAdapterError, type DynamoStore, type IndexMap, type ModelIndexMap, OptimisticLockError, type QueryPage, type QueryPlan, type SingleTableStoreOptions, type StoreItem, type TtlOptions, UniqueConstraintError, UnsupportedQueryError, assignSlots, buildTableDefinition, createSingleTableStore, deriveIndexMap, dynamoAdapter, ensureSchema, generateSchemaFile, isConditionalCheckFailed, isConditionalTransactionCanceled, isTransactionCanceled, matchesResidual, planQuery, transactionCancellationCodes };