@cyphra/better-auth 0.0.0-stage → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +46 -2
- package/dist/index.d.ts +188 -0
- package/dist/index.js +937 -0
- package/dist/index.js.map +1 -0
- package/package.json +65 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Cyphra contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,47 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cyphra/better-auth
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Part of [Cyphra](https://www.cyphra.dev), the TypeScript ORM for Neo4j. **Better Auth:** [docs](https://www.cyphra.dev/better-auth)
|
|
4
|
+
|
|
5
|
+
A [Better Auth](https://www.better-auth.com) database adapter for Neo4j, built on the Cyphra ORM.
|
|
6
|
+
Users, sessions, accounts, verifications and plugin models are nodes in the same graph as your own
|
|
7
|
+
models, described by one `schema.cyphra` and migrated by `cyphra migrate`.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm i @cyphra/better-auth better-auth cyphra
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
// auth.ts
|
|
15
|
+
import { betterAuth } from "better-auth";
|
|
16
|
+
import { cyphraAdapter } from "@cyphra/better-auth";
|
|
17
|
+
import { db } from "./db"; // your generated Cyphra client (createClient from cyphra.gen.ts)
|
|
18
|
+
|
|
19
|
+
export const auth = betterAuth({
|
|
20
|
+
database: cyphraAdapter({ db }),
|
|
21
|
+
emailAndPassword: { enabled: true },
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Pass `{ client }` (a `CyphraClient`) instead of `{ db }` if you have no generated client yet.
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx @better-auth/cli generate # adds the Better Auth models to schema.cyphra, keeps yours
|
|
29
|
+
npx cyphra migrate dev --name better-auth
|
|
30
|
+
npx cyphra generate
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- The schema is derived from your Better Auth configuration (plugins included) at runtime.
|
|
34
|
+
- Labels are the model names in PascalCase: `User`, `Session`, `Account`, `Verification`.
|
|
35
|
+
- Foreign keys are edges, not properties: `Session.userId` is `(User)-[:HAS_SESSION]->(Session)`,
|
|
36
|
+
exposed in the typed client as `session.user` and `user.sessions`.
|
|
37
|
+
- Dates are Neo4j `DateTime` values; `references.onDelete` (`cascade`, `restrict`, `set null`) is
|
|
38
|
+
applied in the same transaction; `consumeOne` and `incrementOne` are race-safe.
|
|
39
|
+
- Passes Better Auth's adapter conformance suites (normal, case-insensitive, transactions, joins,
|
|
40
|
+
uuid, auth flow).
|
|
41
|
+
|
|
42
|
+
Coming from `neo4j-better-auth`? See
|
|
43
|
+
[Migrating from neo4j-better-auth](https://www.cyphra.dev/better-auth#migrating-from-neo4j-better-auth).
|
|
44
|
+
|
|
45
|
+
## License
|
|
46
|
+
|
|
47
|
+
MIT
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import { DBAdapterDebugLogOption, AdapterFactory } from 'better-auth/adapters';
|
|
2
|
+
import { BetterAuthOptions } from 'better-auth/types';
|
|
3
|
+
import { CyphraClient } from '@cyphra/runtime';
|
|
4
|
+
import { BetterAuthDBSchema } from 'better-auth/db';
|
|
5
|
+
import { ScalarTypeName, SchemaDocument, SchemaModel } from '@cyphra/schema';
|
|
6
|
+
|
|
7
|
+
/** Options for {@link cyphraAdapter}. Pass `client` or `db`. */
|
|
8
|
+
interface CyphraAdapterConfig {
|
|
9
|
+
/** A Cyphra client (`new CyphraClient({ uri, user, password })`). */
|
|
10
|
+
client?: CyphraClient;
|
|
11
|
+
/** Your generated Cyphra ORM client; its connection (`db.$client`) is reused. */
|
|
12
|
+
db?: {
|
|
13
|
+
readonly $client: CyphraClient;
|
|
14
|
+
};
|
|
15
|
+
/** Use plural model names (`users`, `sessions`, …). Default `false`. */
|
|
16
|
+
usePlural?: boolean;
|
|
17
|
+
/**
|
|
18
|
+
* Better Auth adapter debug logs. Leave off in production: logs can contain tokens and
|
|
19
|
+
* other sensitive values.
|
|
20
|
+
*/
|
|
21
|
+
debugLogs?: DBAdapterDebugLogOption;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Better Auth database adapter for Neo4j, built on the Cyphra ORM runtime.
|
|
25
|
+
*
|
|
26
|
+
* The Cyphra schema is derived from your Better Auth configuration (plugins included) at
|
|
27
|
+
* runtime. Foreign keys are stored as edges: `Session.userId` is the edge
|
|
28
|
+
* `(User)-[:HAS_SESSION]->(Session)`.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* import { betterAuth } from "better-auth";
|
|
33
|
+
* import { cyphraAdapter } from "@cyphra/better-auth";
|
|
34
|
+
* import { db } from "./db"; // your generated Cyphra client
|
|
35
|
+
*
|
|
36
|
+
* export const auth = betterAuth({ database: cyphraAdapter({ db }) });
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
declare function cyphraAdapter(config: CyphraAdapterConfig): AdapterFactory<BetterAuthOptions>;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Derives a Cyphra schema from Better Auth's database schema (core models plus plugins).
|
|
43
|
+
*
|
|
44
|
+
* - Each Better Auth model becomes a node named after its database model name in PascalCase
|
|
45
|
+
* (`user` → `User`, `user_custom` → `UserCustom`).
|
|
46
|
+
* - A field with `references` (a foreign key such as `Session.userId`) is not stored as a
|
|
47
|
+
* property. It becomes an edge `(User)-[:HAS_SESSION]->(Session)`, a to-one relation field on
|
|
48
|
+
* the child (`user`) and a list field on the parent (`sessions`).
|
|
49
|
+
*
|
|
50
|
+
* @packageDocumentation
|
|
51
|
+
*/
|
|
52
|
+
|
|
53
|
+
/** Mapping functions Better Auth provides to adapters (`getModelName`, `getFieldName`). */
|
|
54
|
+
interface SchemaNaming {
|
|
55
|
+
schema: BetterAuthDBSchema;
|
|
56
|
+
/** Schema key (or custom model name) → database model name. */
|
|
57
|
+
getModelName: (model: string) => string;
|
|
58
|
+
/** Schema field → database field name. */
|
|
59
|
+
getFieldName: (args: {
|
|
60
|
+
model: string;
|
|
61
|
+
field: string;
|
|
62
|
+
}) => string;
|
|
63
|
+
}
|
|
64
|
+
type OnDelete = "no action" | "restrict" | "cascade" | "set null" | "set default";
|
|
65
|
+
interface ScalarMapping {
|
|
66
|
+
readonly kind: "scalar";
|
|
67
|
+
/** Database field name (the property key on the node). */
|
|
68
|
+
readonly name: string;
|
|
69
|
+
readonly type: ScalarTypeName;
|
|
70
|
+
readonly list: boolean;
|
|
71
|
+
/** Better Auth's `unique` / `index` flags. */
|
|
72
|
+
readonly unique: boolean;
|
|
73
|
+
readonly index: boolean;
|
|
74
|
+
}
|
|
75
|
+
interface ForeignKeyMapping {
|
|
76
|
+
readonly kind: "fk";
|
|
77
|
+
/** Database field name Better Auth reads and writes, e.g. `userId`. */
|
|
78
|
+
readonly name: string;
|
|
79
|
+
/** To-one relation field on the child node, e.g. `user`. */
|
|
80
|
+
readonly relation: string;
|
|
81
|
+
/** Schema key of the referenced model, e.g. `user`. */
|
|
82
|
+
readonly parentKey: string;
|
|
83
|
+
/** Database field name of the referenced field on the parent (usually `id`). */
|
|
84
|
+
readonly refField: string;
|
|
85
|
+
readonly relType: string;
|
|
86
|
+
/** List relation field on the parent node, e.g. `sessions`. */
|
|
87
|
+
readonly inverse: string;
|
|
88
|
+
readonly onDelete: OnDelete;
|
|
89
|
+
readonly unique: boolean;
|
|
90
|
+
readonly index: boolean;
|
|
91
|
+
readonly required: boolean;
|
|
92
|
+
}
|
|
93
|
+
type FieldMapping = ScalarMapping | ForeignKeyMapping;
|
|
94
|
+
interface ModelMapping {
|
|
95
|
+
/** Better Auth schema key, e.g. `user`. */
|
|
96
|
+
readonly key: string;
|
|
97
|
+
/** Database model name, e.g. `user` or `users` with `usePlural`. */
|
|
98
|
+
readonly dbName: string;
|
|
99
|
+
/** Cyphra node name and Neo4j label, e.g. `User`. */
|
|
100
|
+
readonly node: string;
|
|
101
|
+
/** ORM delegate key, e.g. `user` or `twoFactor`. */
|
|
102
|
+
readonly delegate: string;
|
|
103
|
+
/** Database name of the id field. */
|
|
104
|
+
readonly idField: string;
|
|
105
|
+
/** Every Better Auth field by database name (the id included, as a scalar). */
|
|
106
|
+
readonly fields: ReadonlyMap<string, FieldMapping>;
|
|
107
|
+
readonly foreignKeys: readonly ForeignKeyMapping[];
|
|
108
|
+
}
|
|
109
|
+
interface AuthGraph {
|
|
110
|
+
/** By Better Auth schema key. */
|
|
111
|
+
readonly models: ReadonlyMap<string, ModelMapping>;
|
|
112
|
+
/** The auth nodes as a `.cyphra` document (used by `createSchema`). */
|
|
113
|
+
readonly document: SchemaDocument;
|
|
114
|
+
/** The resolved model the ORM runtime runs on. */
|
|
115
|
+
readonly schema: SchemaModel;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Build the auth graph (node mappings, `.cyphra` document and resolved schema model) for a
|
|
119
|
+
* Better Auth configuration.
|
|
120
|
+
*/
|
|
121
|
+
declare function deriveAuthGraph(naming: SchemaNaming): AuthGraph;
|
|
122
|
+
|
|
123
|
+
/** Naming options that must match the ones passed to `cyphraAdapter`. */
|
|
124
|
+
interface AuthSchemaOptions {
|
|
125
|
+
usePlural?: boolean;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* The Cyphra schema for a Better Auth configuration: the same one the adapter derives at
|
|
129
|
+
* runtime. `document` is the `.cyphra` AST (print it with `printSchemaDocument`), `schema` the
|
|
130
|
+
* resolved model (use it with `createOrm` or the migrator).
|
|
131
|
+
*
|
|
132
|
+
* @example
|
|
133
|
+
* ```ts
|
|
134
|
+
* import { constraintStatementsFromSchema } from "@cyphra/migrator";
|
|
135
|
+
* const { document } = authSchema(auth.options);
|
|
136
|
+
* constraintStatementsFromSchema(document); // CREATE CONSTRAINT … for User, Session, …
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
139
|
+
declare function authSchema(options: BetterAuthOptions, naming?: AuthSchemaOptions): AuthGraph;
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Cypher that converts data written by `neo4j-better-auth` (0.x) to the layout this adapter
|
|
143
|
+
* uses.
|
|
144
|
+
*
|
|
145
|
+
* | neo4j-better-auth | @cyphra/better-auth |
|
|
146
|
+
* | ------------------------------------------- | ----------------------------------------- |
|
|
147
|
+
* | label = database model name (`user`) | PascalCase label (`User`) |
|
|
148
|
+
* | foreign key property + `HAS_*` edge | `HAS_*` edge only |
|
|
149
|
+
* | dates as ISO strings | `DateTime` values |
|
|
150
|
+
* | numbers as floats | integers (`Int`) |
|
|
151
|
+
*
|
|
152
|
+
* @packageDocumentation
|
|
153
|
+
*/
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Cypher statements, in order, that migrate a graph written by `neo4j-better-auth` for the
|
|
157
|
+
* same Better Auth configuration. Run them once, then create the new constraints with
|
|
158
|
+
* `cyphra migrate deploy` (or `cyphra db push`). Every statement is idempotent.
|
|
159
|
+
*
|
|
160
|
+
* Steps: drop the old constraints and indexes, relabel nodes, rebuild the `HAS_*` edges from the
|
|
161
|
+
* foreign-key properties and remove those properties, convert ISO date strings to `datetime()`
|
|
162
|
+
* and float numbers to integers.
|
|
163
|
+
*
|
|
164
|
+
* @param options - Your Better Auth options (plugins included).
|
|
165
|
+
* @param naming - Must match the `usePlural` you used with neo4j-better-auth.
|
|
166
|
+
*/
|
|
167
|
+
declare function neo4jBetterAuthMigration(options: BetterAuthOptions, naming?: AuthSchemaOptions): string[];
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Writes the Better Auth nodes into an existing `schema.cyphra` without touching anything else.
|
|
171
|
+
*
|
|
172
|
+
* Fields of auth nodes that Better Auth defines are added or updated in place, line by line.
|
|
173
|
+
* Everything else is kept as written, comments included: your own models, relationships, and
|
|
174
|
+
* fields you added to auth nodes (for example `projects Project[]` on `User`).
|
|
175
|
+
*
|
|
176
|
+
* @packageDocumentation
|
|
177
|
+
*/
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* The `.cyphra` source with the Better Auth nodes of `authDoc` added or updated.
|
|
181
|
+
*
|
|
182
|
+
* @param existing - Current contents of `schema.cyphra`, or `undefined` if there is none.
|
|
183
|
+
* @param authDoc - Auth nodes derived from the Better Auth configuration.
|
|
184
|
+
* @throws When the existing file does not parse, or the merged schema does not resolve.
|
|
185
|
+
*/
|
|
186
|
+
declare function mergeAuthSchema(existing: string | undefined, authDoc: SchemaDocument): string;
|
|
187
|
+
|
|
188
|
+
export { type AuthGraph, type AuthSchemaOptions, type CyphraAdapterConfig, type FieldMapping, type ForeignKeyMapping, type ModelMapping, type OnDelete, type ScalarMapping, type SchemaNaming, authSchema, cyphraAdapter, deriveAuthGraph, mergeAuthSchema, neo4jBetterAuthMigration };
|