@authhero/aws-adapter 1.1.3 → 1.1.6

package/dist/types/cursor.d.ts

@@ -0,0 +1,39 @@
+/** A DynamoDB `LastEvaluatedKey` / `ExclusiveStartKey`. */
+export type DynamoKey = Record<string, string>;
+/**
+ * The query a cursor must belong to. Every tenant-scoped entity shares the
+ * partition key `TENANT#{id}` and is separated only by its sort-key prefix, so
+ * the prefix is part of a cursor's identity, not a detail.
+ */
+export interface CursorQuery {
+    /** Partition key value the query filters on. */
+    pk: string;
+    /** GSI being queried, if any. Its keys are named `{indexName}PK`/`SK`. */
+    indexName?: string;
+    /** `begins_with` prefix applied to the sort key, if any. */
+    skPrefix?: string;
+}
+/**
+ * Encode a `LastEvaluatedKey` into an opaque cursor token suitable for
+ * returning as `next` and accepting back as `from`.
+ */
+export declare function encodeDynamoCursor(key: Record<string, unknown>): string;
+/**
+ * Decode an opaque cursor token into an `ExclusiveStartKey`, verifying it was
+ * minted by the same query that is now presenting it.
+ *
+ * Returns `null` for anything unusable so a client-supplied `from` degrades to
+ * "start from the beginning" rather than throwing — matching `decodeCursor()`
+ * in adapter-interfaces.
+ *
+ * The query check is not decoration. DynamoDB rejects a key that disagrees with
+ * the query's key conditions ("The provided starting key does not match the
+ * range key predicate", "...is invalid"), so without this an attacker-supplied
+ * or merely stale `from` turns into an unhandled ValidationException — a 500
+ * driven by a query parameter. Note that this validation is a robustness
+ * measure, not a tenant boundary: DynamoDB already refuses a cursor whose
+ * partition key differs from the one being queried, so a foreign cursor could
+ * never read another tenant's rows. It fails cleanly here instead of loudly
+ * there.
+ */
+export declare function decodeDynamoCursor(token: string, query: CursorQuery): DynamoKey | null;

package/dist/types/utils.d.ts

@@ -41,8 +41,21 @@ export declare function queryItems<T>(ctx: DynamoDBContext, pk: string, options?
     items: T[];
     lastKey?: Record<string, unknown>;
 }>;
+/** True when the caller asked for keyset (checkpoint) pagination. */
+export declare function isKeysetRequest(params?: ListParams): boolean;
 /**
- * Query with pagination support
+ * Query with pagination support.
+ *
+ * Two modes, picked by which parameters the caller supplied:
+ *
+ * - **Keyset (checkpoint)** — `from`/`take`. `from` is an OPAQUE cursor (see
+ *   `encodeDynamoCursor`) wrapping DynamoDB's own `LastEvaluatedKey`, so a page
+ *   resumes natively via `ExclusiveStartKey` with no scanning of skipped rows.
+ *   Returns `next` when a further page may exist, and no `total` — matching
+ *   Auth0's checkpoint responses and the SQL adapters.
+ * - **Offset** — `page`/`per_page`. Unchanged, including the read-and-discard
+ *   loop DynamoDB forces on us (it has no native offset). The admin UI uses
+ *   this, and it is what `include_totals` is for.
  */
 export declare function queryWithPagination<T>(ctx: DynamoDBContext, pk: string, params?: ListParams, options?: {
     skPrefix?: string;
@@ -54,6 +67,8 @@ export declare function queryWithPagination<T>(ctx: DynamoDBContext, pk: string,
     limit: number;
     length: number;
     total?: number;
+    /** Opaque cursor for the next page; keyset mode only, absent on the last. */
+    next?: string;
 }>;
 /**
  * Generic update operation for DynamoDB

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "1.1.3",
+  "version": "1.1.6",
   "files": [
     "dist"
   ],
@@ -44,8 +44,8 @@
     "@aws-sdk/client-dynamodb": "^3.1085.0",
     "@aws-sdk/lib-dynamodb": "^3.1085.0",
     "nanoid": "^5.1.11",
-    "@authhero/adapter-interfaces": "4.7.0",
-    "@authhero/proxy": "0.10.4"
+    "@authhero/adapter-interfaces": "4.8.0",
+    "@authhero/proxy": "0.10.6"
   },
   "license": "AGPL-3.0-only",
   "scripts": {