@cyphra/graphql 0.6.0 → 0.8.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/README.md CHANGED
@@ -28,9 +28,33 @@ Status (early release):
28
28
  - Mutations: `create`, `update`, `delete` with `info` counters, nested `create` / `connect` /
29
29
  `disconnect` / `update` / `delete` with edge properties, every update operator (deprecated forms
30
30
  included), `@id`, `@timestamp` and `@default`. No APOC needed.
31
+ - `@authentication` / `@authorization` (type, field and `extend schema` level), `@jwt` and
32
+ `@jwtClaim`: rules are compiled into the Cypher statement (filters in its `WHERE`, `validate`
33
+ checks inside it, a failed check rolls the statement back), never applied in JavaScript.
34
+ - `@cypher` fields on node types, relationship properties, `Query` and `Mutation`: scalar and
35
+ node results, arguments (always passed as parameters), `this`, `$jwt`, `where` and `sort` on
36
+ scalar fields, filters on node results, the READ rules of returned nodes.
37
+ - `@fulltext` queries (`score`, `where`, `sort`, `first` / `after`) on full-text indexes you
38
+ create, as in v7.
31
39
  - One Cypher statement per root field, in its own transaction. Needs Neo4j 5.23+.
32
- - Not yet: `@authentication` / `@authorization` (#74) and `@cypher` fields (#75). They are in the
33
- schema and return a `Not implemented yet` error.
40
+ - Not yet: interfaces, unions, subscriptions, `@vector`, `Point` / `Duration` and custom scalars
41
+ (`makeSchema` throws `UnsupportedTypeDefsError`).
42
+
43
+ JWTs are verified like v7, with `features.authorization` and the request's `Authorization` header
44
+ as `token` in the context (a decoded `jwt` in the context is trusted as it is):
45
+
46
+ ```ts
47
+ const schema = compat.v7.makeSchema({
48
+ typeDefs,
49
+ driver,
50
+ features: { authorization: { key: process.env.JWT_SECRET! } }, // or { key: { url: jwksUrl } }
51
+ });
52
+ // GraphQL server context: ({ request }) => ({ token: request.headers.get("authorization") })
53
+ ```
54
+
55
+ Read the [authorization docs](https://www.cyphra.dev/graphql#authentication-and-authorization) for
56
+ the v7 behaviours that matter for security (filters on fields the user cannot read, AGGREGATE vs
57
+ READ rules, relationship-only updates) and the few cases where Cyphra is stricter than v7.
34
58
 
35
59
  Compatibility is measured against the real `@neo4j/graphql` by the suite in
36
60
  [`compat/graphql`](https://github.com/Cyphra-dev/cyphra/tree/main/compat/graphql).
package/dist/index.d.ts CHANGED
@@ -2,13 +2,14 @@ import { ConstValueNode, GraphQLSchema } from 'graphql';
2
2
  import { SchemaDocument, SchemaModel } from '@cyphra/schema';
3
3
  import { CyphraClient } from '@cyphra/runtime';
4
4
  import { Driver } from 'neo4j-driver';
5
+ import { RemoteJWKSetOptions, JWTVerifyOptions } from 'jose';
5
6
 
6
7
  /**
7
8
  * The mapping from `@neo4j/graphql` v7 type definitions to Cyphra, in one place.
8
9
  *
9
10
  * Each GraphQL scalar, type-level directive and field-level directive has one entry here. When
10
- * Cyphra gains a feature (enums, `BigInt`, `Point`, …), supporting it in the importer means
11
- * changing that entry: the converter in `convert.ts` only walks the SDL and applies these rules.
11
+ * Cyphra gains a feature (`Point`, `Duration`, …), supporting it in the importer means changing
12
+ * that entry: the converter in `convert.ts` only walks the SDL and applies these rules.
12
13
  *
13
14
  * Semantics follow `@neo4j/graphql` 7.x (checked against 7.6.8):
14
15
  * - only object types with `@node` are nodes; `@node(labels)` sets the Neo4j labels;
@@ -122,6 +123,37 @@ type ExecutorOptions = {
122
123
  debug?: boolean;
123
124
  };
124
125
 
126
+ /**
127
+ * JWT verification for `@authentication` / `@authorization`, configured like `@neo4j/graphql` v7
128
+ * (`features.authorization`): the bearer token of the request (`context.token`) is verified with
129
+ * `jose` against a symmetric secret or a JWKS endpoint. A token that is missing, malformed, expired,
130
+ * not yet valid or signed with another key leaves the request unauthenticated (no error), like v7.
131
+ *
132
+ * @packageDocumentation
133
+ */
134
+
135
+ type AnyRecord$1 = Record<string, unknown>;
136
+ /** A symmetric secret (HS256 / HS384 / HS512), or the URL of a JWKS endpoint. */
137
+ type JwtKey = string | {
138
+ url: string;
139
+ options?: RemoteJWKSetOptions;
140
+ };
141
+ /** `features.authorization` of `Neo4jGraphQL`: how tokens are verified. */
142
+ type AuthorizationFeature = {
143
+ /** The key, or a function of the GraphQL context returning it (per request). */
144
+ key: JwtKey | ((context: AnyRecord$1) => JwtKey);
145
+ /**
146
+ * `false` decodes tokens without verifying the signature (v7 option). Only for tokens already
147
+ * verified upstream (e.g. by a gateway): anyone can forge an unverified token.
148
+ */
149
+ verify?: boolean;
150
+ /** Passed to `jose`'s `jwtVerify` (`issuer`, `audience`, `algorithms`, `clockTolerance`, …). */
151
+ verifyOptions?: JWTVerifyOptions;
152
+ };
153
+ type Features = {
154
+ authorization?: AuthorizationFeature;
155
+ };
156
+
125
157
  /**
126
158
  * The `@neo4j/graphql` v7 type definitions, read into the model the v7 API is generated from.
127
159
  *
@@ -145,6 +177,51 @@ type CypherAnnotation = {
145
177
  readonly statement: string;
146
178
  readonly columnName: string;
147
179
  };
180
+ /** An argument of a `@cypher` field (scalar or enum, list or not), e.g. `tags(prefix: String = "x")`. */
181
+ type FieldArgument = {
182
+ readonly name: string;
183
+ readonly type: TypeRef;
184
+ readonly kind: "scalar" | "enum";
185
+ readonly description?: string;
186
+ /** The raw default value AST, printed in the SDL and applied by GraphQL. */
187
+ readonly defaultAst?: ConstValueNode;
188
+ };
189
+ /** A `@cypher` field of a node type returning nodes (`[Person!]!` or `Person`). */
190
+ type CypherNodeField = {
191
+ readonly name: string;
192
+ /** Node type of the returned nodes. */
193
+ readonly target: string;
194
+ readonly type: TypeRef;
195
+ readonly cypher: CypherAnnotation;
196
+ readonly args: readonly FieldArgument[];
197
+ readonly description?: string;
198
+ readonly deprecated?: string;
199
+ };
200
+ /** A `@cypher` field of `Query` or `Mutation`. */
201
+ type CypherRootField = {
202
+ readonly name: string;
203
+ readonly type: TypeRef;
204
+ /** `node` when the named type is a `@node` type. */
205
+ readonly kind: "scalar" | "enum" | "node";
206
+ readonly cypher: CypherAnnotation;
207
+ readonly args: readonly FieldArgument[];
208
+ readonly description?: string;
209
+ readonly deprecated?: string;
210
+ /** Field-level `@authentication`. */
211
+ readonly authentication?: AuthenticationAnnotation;
212
+ };
213
+ /** The custom fields of `Query` or `Mutation`, with the type-level `@authentication`. */
214
+ type CypherRootType = {
215
+ readonly fields: readonly CypherRootField[];
216
+ readonly authentication?: AuthenticationAnnotation;
217
+ };
218
+ /** One index of `@fulltext(indexes: [{ indexName, queryName, fields }])`. */
219
+ type FulltextIndex = {
220
+ readonly indexName: string;
221
+ /** Root query field, e.g. `moviesByTitle`. */
222
+ readonly queryName: string;
223
+ readonly fields: readonly string[];
224
+ };
148
225
  type Attribute = {
149
226
  readonly name: string;
150
227
  /** Property key in Neo4j (`@alias(property)`), defaults to the field name. */
@@ -161,8 +238,12 @@ type Attribute = {
161
238
  /** `@timestamp(operations)`. */
162
239
  readonly timestamp?: readonly ("CREATE" | "UPDATE")[];
163
240
  readonly cypher?: CypherAnnotation;
241
+ /** Arguments of a `@cypher` field (other fields have none). */
242
+ readonly args: readonly FieldArgument[];
164
243
  /** User `@deprecated(reason)` on the field. */
165
244
  readonly deprecated?: string;
245
+ /** Field-level `@authentication` / `@authorization`. */
246
+ readonly auth?: AuthAnnotations;
166
247
  };
167
248
  type Relationship = {
168
249
  readonly name: string;
@@ -178,11 +259,37 @@ type Relationship = {
178
259
  readonly description?: string;
179
260
  readonly deprecated?: string;
180
261
  };
181
- type AuthRules = {
182
- /** Operations covered by `@authentication` (all operations when the directive has no args). */
183
- readonly authentication?: readonly string[];
184
- /** `@authorization` present on the type. */
185
- readonly authorization: boolean;
262
+ /** Operations `@authentication` / `@authorization` rules apply to. */
263
+ declare const AUTH_OPERATIONS: readonly ["READ", "AGGREGATE", "CREATE", "UPDATE", "DELETE", "CREATE_RELATIONSHIP", "DELETE_RELATIONSHIP", "SUBSCRIBE"];
264
+ type AuthOperation = (typeof AUTH_OPERATIONS)[number];
265
+ type AnyRecord = Record<string, unknown>;
266
+ /** `@authentication(operations, jwt)`. */
267
+ type AuthenticationAnnotation = {
268
+ readonly operations: ReadonlySet<AuthOperation>;
269
+ /** `jwt: { … }` filter the decoded JWT must match (checked in JS, before the statement runs). */
270
+ readonly jwt?: AnyRecord;
271
+ };
272
+ /** One `filter` rule of `@authorization`. */
273
+ type AuthorizationRule = {
274
+ readonly operations: readonly AuthOperation[];
275
+ /** Default `true`: the rule only holds for authenticated requests. */
276
+ readonly requireAuthentication: boolean;
277
+ /** `{ node, jwt, AND, OR, NOT }` with `$jwt.<claim>` / `$context.<path>` string references. */
278
+ readonly where: AnyRecord;
279
+ };
280
+ /** One `validate` rule of `@authorization`. */
281
+ type AuthorizationValidateRule = AuthorizationRule & {
282
+ /** Default both: checked before and after the write. */
283
+ readonly when: readonly ("BEFORE" | "AFTER")[];
284
+ };
285
+ type AuthorizationAnnotation = {
286
+ readonly filter: readonly AuthorizationRule[];
287
+ readonly validate: readonly AuthorizationValidateRule[];
288
+ };
289
+ /** `@authentication` / `@authorization` of a type or of a field. */
290
+ type AuthAnnotations = {
291
+ readonly authentication?: AuthenticationAnnotation;
292
+ readonly authorization?: AuthorizationAnnotation;
186
293
  };
187
294
  type NodeType = {
188
295
  readonly name: string;
@@ -195,7 +302,11 @@ type NodeType = {
195
302
  readonly pascalPlural: string;
196
303
  readonly attributes: readonly Attribute[];
197
304
  readonly relationships: readonly Relationship[];
198
- readonly auth: AuthRules;
305
+ /** `@cypher` fields returning nodes. */
306
+ readonly cypherNodes: readonly CypherNodeField[];
307
+ /** `@fulltext` indexes. */
308
+ readonly fulltext: readonly FulltextIndex[];
309
+ readonly auth: AuthAnnotations;
199
310
  };
200
311
  type PropertiesType = {
201
312
  readonly name: string;
@@ -212,8 +323,18 @@ type EnumType = {
212
323
  };
213
324
  type V7Model = {
214
325
  readonly nodes: readonly NodeType[];
326
+ /** Schema-level `extend schema @authentication(…)`: applies to every operation on every type. */
327
+ readonly authentication?: AuthenticationAnnotation;
328
+ /**
329
+ * `@jwtClaim(path)` of the `@jwt` type: field name → dotted path in the JWT payload. Like v7, the
330
+ * mapping is applied to tokens the library verified, not to a decoded `jwt` passed in the context.
331
+ */
332
+ readonly jwtClaims: ReadonlyMap<string, string>;
215
333
  readonly properties: ReadonlyMap<string, PropertiesType>;
216
334
  readonly enums: ReadonlyMap<string, EnumType>;
335
+ /** `@cypher` fields of `type Query` / `type Mutation`. */
336
+ readonly query: CypherRootType;
337
+ readonly mutation: CypherRootType;
217
338
  node(name: string): NodeType;
218
339
  };
219
340
  /** The type definitions use a feature `@cyphra/graphql` cannot serve yet. */
@@ -256,6 +377,13 @@ declare function buildV7Schema(model: V7Model): GraphQLSchema;
256
377
  * the last / first values ordered by `size(…)` descending; `sum` of an empty set is `0`, the other
257
378
  * aggregates are `null`. Int `average` is a Float, BigInt values (including `average`) are strings.
258
379
  *
380
+ * Authorization (v7 7.6): the READ `filter` rules of the type (and of the selected fields) are part
381
+ * of the `WHERE` of every node selection, root or nested, and of connection `totalCount`; connection
382
+ * `aggregate` selections use the AGGREGATE rules instead. When READ (AGGREGATE) `validate` rules fail
383
+ * for one node matching the selection's filters (before pagination, like v7), the selection is
384
+ * replaced by a {@link FORBIDDEN_KEY} marker and the field fails with `Forbidden`: the projection of
385
+ * a node that is not allowed is never returned by the database.
386
+ *
259
387
  * @packageDocumentation
260
388
  */
261
389
 
@@ -272,6 +400,13 @@ declare function cursorToOffset(cursor: unknown): number | undefined;
272
400
  type MakeSchemaOptions = ExecutorOptions & {
273
401
  /** v7 type definitions (`@node`, `@relationship`, …). */
274
402
  typeDefs: string;
403
+ /**
404
+ * v7 `features`. `authorization` configures JWT verification for `@authentication` /
405
+ * `@authorization`: the request's `context.token` (`Bearer <jwt>`) is verified with `key` (a
406
+ * secret, a JWKS `{ url }`, or a function of the context returning one). Without it, only a
407
+ * decoded `context.jwt` (trusted as-is) authenticates requests.
408
+ */
409
+ features?: Features;
275
410
  };
276
411
  /**
277
412
  * Build the GraphQL schema `@neo4j/graphql` v7 generates for `typeDefs`, with resolvers that run on
@@ -279,9 +414,11 @@ type MakeSchemaOptions = ExecutorOptions & {
279
414
  *
280
415
  * Today: the full v7 schema (SDL identical to v7), the read API (list and connection queries,
281
416
  * filters, sorting, offset and cursor pagination, nested relationships and connections with edge
282
- * properties, connection `aggregate` selections and aggregation filters) and mutations (create,
283
- * update, delete with every nested operation and `info` counters). Authorization (#74) and
284
- * `@cypher` fields (#75) are in the schema but answer with a "Not implemented yet" error.
417
+ * properties, connection `aggregate` selections and aggregation filters), mutations (create,
418
+ * update, delete with every nested operation and `info` counters) and `@authentication` /
419
+ * `@authorization` (compiled into each statement; JWTs verified with `features.authorization`),
420
+ * `@cypher` fields (on node types, relationship properties, `Query` and `Mutation`; sortable and
421
+ * filterable like v7) and `@fulltext` queries (on indexes the application creates).
285
422
  *
286
423
  * @example
287
424
  * ```ts
@@ -291,11 +428,15 @@ type MakeSchemaOptions = ExecutorOptions & {
291
428
  */
292
429
  declare function makeSchema(options: MakeSchemaOptions): GraphQLSchema;
293
430
  /**
294
- * The GraphQL `contextValue` for a request. v7 reads the decoded JWT from `context.jwt`; it is
295
- * accepted for compatibility (authorization itself is #74).
431
+ * The GraphQL `contextValue` for a request, as v7 reads it: `token` is the `Authorization` header
432
+ * (`Bearer <jwt>`, verified with `features.authorization`), `jwt` a payload the server already
433
+ * verified (trusted as-is, takes precedence over `token`). Other keys are kept for
434
+ * `$context.<path>` references in rules.
296
435
  */
297
436
  declare function contextFor(opts?: {
298
437
  jwt?: Record<string, unknown>;
438
+ token?: string;
439
+ [key: string]: unknown;
299
440
  }): Record<string, unknown>;
300
441
  /**
301
442
  * The Cyphra schema for the same type definitions (through `convertGraphQLTypeDefs`, the converter
@@ -308,6 +449,9 @@ declare function cyphraSchema(typeDefs: string): {
308
449
  issues: readonly ImportIssue[];
309
450
  };
310
451
 
452
+ type v7_AuthorizationFeature = AuthorizationFeature;
453
+ type v7_Features = Features;
454
+ type v7_JwtKey = JwtKey;
311
455
  type v7_MakeSchemaOptions = MakeSchemaOptions;
312
456
  type v7_UnsupportedTypeDefsError = UnsupportedTypeDefsError;
313
457
  declare const v7_UnsupportedTypeDefsError: typeof UnsupportedTypeDefsError;
@@ -320,7 +464,7 @@ declare const v7_makeSchema: typeof makeSchema;
320
464
  declare const v7_offsetToCursor: typeof offsetToCursor;
321
465
  declare const v7_readTypeDefs: typeof readTypeDefs;
322
466
  declare namespace v7 {
323
- export { type v7_MakeSchemaOptions as MakeSchemaOptions, v7_UnsupportedTypeDefsError as UnsupportedTypeDefsError, type v7_V7Model as V7Model, v7_buildV7Schema as buildV7Schema, v7_contextFor as contextFor, v7_cursorToOffset as cursorToOffset, v7_cyphraSchema as cyphraSchema, v7_makeSchema as makeSchema, v7_offsetToCursor as offsetToCursor, v7_readTypeDefs as readTypeDefs };
467
+ export { type v7_AuthorizationFeature as AuthorizationFeature, type v7_Features as Features, type v7_JwtKey as JwtKey, type v7_MakeSchemaOptions as MakeSchemaOptions, v7_UnsupportedTypeDefsError as UnsupportedTypeDefsError, type v7_V7Model as V7Model, v7_buildV7Schema as buildV7Schema, v7_contextFor as contextFor, v7_cursorToOffset as cursorToOffset, v7_cyphraSchema as cyphraSchema, v7_makeSchema as makeSchema, v7_offsetToCursor as offsetToCursor, v7_readTypeDefs as readTypeDefs };
324
468
  }
325
469
 
326
470
  /**
@@ -336,4 +480,4 @@ declare const compat: {
336
480
  readonly v7: typeof v7;
337
481
  };
338
482
 
339
- export { GraphQLImportError, type GraphQLImportResult, type GraphQLSource, type ImportIssue, type ImportSeverity, type MakeSchemaOptions, UnsupportedTypeDefsError, compat, convertGraphQLTypeDefs, formatImportReport, mergeImportedSchema, printImportedSchema };
483
+ export { type AuthorizationFeature, type Features, GraphQLImportError, type GraphQLImportResult, type GraphQLSource, type ImportIssue, type ImportSeverity, type JwtKey, type MakeSchemaOptions, UnsupportedTypeDefsError, compat, convertGraphQLTypeDefs, formatImportReport, mergeImportedSchema, printImportedSchema };