@nxgt/shared-graphql 2.0.0 → 2.1.0

package/README.md

@@ -10,9 +10,16 @@ and the SDL every service merges into its own schema.
 bun add @nxgt/shared-graphql
 ```
 
-Public on npmjs; no token needed to install. TypeScript is a peer, pinned to
-`^6.0.3` across every `@nxgt/*` package — the set is unsatisfiable if one of
-them widens it. **`stx-sdk` is a required peer** (`>=1.1.0`).
+Public on npmjs; no token needed to install. Peers:
+
+| Peer | Range | Why |
+| --- | --- | --- |
+| `graphql` | `^16.4.2 \|\| ^17.0.0` | one copy for your schema and this package's transforms; the suite runs on both majors |
+| `@nxgt/ory-sdk` | `>=0.1.0` | `useOryAuth`, `useKetoChecks`, `can` |
+| `stx-sdk` | `>=1.1.0` | `./security`'s policy types |
+| `typescript` | `^6.0.3` | pinned across every `@nxgt/*` package — the set is unsatisfiable if one of them widens it |
+
+The long version of each section below is in [`docs/`](./docs/README.md).
 
 ## Subpaths
 
@@ -31,9 +38,13 @@ walking up to the nearest `package.json` — the bundle is `dist/index.js`, the
 source is `src/utils/schema.utils.ts`, and no single relative path serves both.
 
 ```ts
-import { loadTypeDefs, SCALAR_RESOLVERS, SHARED_SCHEMA_PATH } from '@nxgt/shared-graphql';
+import { fileURLToPath } from 'node:url';
+import { loadTypeDefs, SHARED_SCHEMA_PATH } from '@nxgt/shared-graphql';
 
-const typeDefs = loadTypeDefs(SHARED_SCHEMA_PATH, join(__dirname, '../**/*.graphqls'));
+const typeDefs = loadTypeDefs(
+	SHARED_SCHEMA_PATH,
+	fileURLToPath(new URL('../**/*.graphqls', import.meta.url)),
+);
 ```
 
 ```ts
@@ -47,107 +58,148 @@ A relative path into this package's `src/` will not work from an install — it
 is not published, and it was not there in the first place.
 
 `SHARED_TYPE_DEFS` is a string of the shared directives (`@authenticated`,
-`@policy`, `@shareable`, `@link`) plus empty root types. A subgraph that
+`@policy`, `@shareable`, `@link`) plus empty root types. `@permission` and
+`@check` are not in it: they live in `graphql/directives/`, so a subgraph that
 builds through `buildSubgraphSchema` and never loads `SHARED_TYPE_DEFS` still
-sees `@check`, because that declaration lives in `graphql/directives/` and
-rides `SHARED_SCHEMA_PATH`. A directive put *only* in `SHARED_TYPE_DEFS`
-would be invisible to exactly the schemas most likely to want it.
+sees them through `SHARED_SCHEMA_PATH`. For a schema assembled in code, the
+same declarations ship as strings — `PERMISSION_DIRECTIVE_SDL`,
+`CHECK_DIRECTIVE_SDL`, or both as `KETO_DIRECTIVES_SDL` — held equal to the
+files by a spec.
+
+```ts
+import { KETO_DIRECTIVES_SDL } from '@nxgt/shared-graphql';
+
+createSchema({ typeDefs: [KETO_DIRECTIVES_SDL, typeDefs], resolvers });
+```
 
 `buildSubgraphSchema` wraps Apollo's builder and prunes unused types.
 
-## `@check` — the permission a field requires
+## `@permission` — the permission a field requires
 
 `@authenticated` asks whether anyone is calling. `@policy` asks whether they
 *carry* an authority. Neither can ask what an Ory-native API needs to know:
 **may this caller `view` `Note:n1`** — a question about one object, answered by
-Keto.
-
-`@check` asks it. The declaration ships in `graphql/directives/check.graphqls`,
-so any schema built from `SHARED_SCHEMA_PATH` already has it; `useKetoChecks(ory)`
-is what answers it.
+Keto. `@permission` asks it; `useKetoChecks(ory)` answers it.
 
 ```graphql
-note(id: ID!): Note!
-	@check(permissions: [[{ namespace: "Note", permit: "view" }]])
+note(id: ID!): Note! @permission(name: "view", type: "Note")
 
 updateNote(id: ID!, input: UpdateNoteInput!): Note!
-	@check(permissions: [[{ namespace: "Note", permit: "view" }]])
-	@check(permissions: [[{ namespace: "Note", permit: "edit" }]], onDeny: FORBIDDEN)
+	@permission(name: "view", type: "Note")
+	@permission(name: "edit", type: "Note", onDeny: FORBIDDEN)
+
+owner: Person @permission(name: "view", type: "Person", id: "parent.ownerId")
 ```
 
 ```ts
-plugins: [useOryAuth(ory), useKetoChecks(ory), useGenericAuth({ … })]
+plugins: [useOryAuth(ory), useKetoChecks(ory, { namespaces: ['Note', 'Person'] }), useGenericAuth({ … })]
 ```
 
-`permissions` is disjunctive normal form — **outer list OR, inner list AND**,
-the same shape `@policy(policies: [["ADMIN"]])` uses. `[[A, B], [C]]` reads
-"(A and B) or C", and evaluation is short-circuit in both directions, so the
-order written is the order Keto is billed for.
-
-`id` defaults to `args.id` and may be any `args.<path>` or `source.<path>`. A
-value that turns out to be a **list** requires the permit on every element —
-that is what `deleteNotes(ids: [ID!]!)` means.
-
-**The directive is repeatable, and that is how 404 and 403 stay distinct.**
-Checks run in declaration order with their own `onDeny`: a stranger fails the
-`view` check and gets `NOT_FOUND`, so an id cannot be probed; a viewer passes
-it, fails `edit`, and gets `FORBIDDEN`, which is honest because they already
-know the object exists.
-
-**Word the refusal like the layer beneath it.** `message:` sets the i18n key a
-denial carries; without it the shared `errors.not-found` /
-`errors.insufficient-permissions` are used. It matters because these fields are
-guarded twice — by the directive, and by the `require<M>Access` their service
-calls — and if the two word one 404 differently, the wording alone tells the
-caller which refused: a generic message means "you may not", a domain one means
-"it is gone". That is the distinction `NOT_FOUND` exists to hide.
+- `name` is the permit, `type` the Keto namespace, `id` where the object id
+  is read: `args.<path>` (default `args.id`) or `parent.<path>`. A **list**
+  value requires the permit on every element.
+- **Repeated, they are AND**, in declaration order, each with its own
+  `onDeny`: a stranger fails `view` and gets `NOT_FOUND` (the default), so an
+  id cannot be probed; a viewer passes it, fails `edit`, and gets `FORBIDDEN`.
+- `message:` sets the i18n key a denial carries (shared `errors.not-found` /
+  `errors.insufficient-permissions` otherwise). Word it like the service
+  layer that guards the same object, or the wording tells a caller which
+  layer refused.
+- An OR belongs in the Keto model — a permit that unions two relations — not
+  in the schema.
+
+**Refused when the schema is built**, as a `TypeError` naming `Type.field`: a
+path naming no root, an `args.<name>` the field does not declare, a namespace
+outside `namespaces` (when you pass them), and a guard on an interface field,
+where no resolver runs. On a `@check`, the undeclared argument and the
+interface field are logged as warnings instead, since 2.x booted with them;
+the next major refuses them there too.
+
+`@permission` is read only when its declaration has `name` and `type` — a
+schema with its own `@permission` of another shape keeps it. Loading this
+package's `graphql/` next to such a declaration merges the two, though: see
+[troubleshooting](./docs/troubleshooting.md).
+
+**An outage is never a denial.** A Keto failure throws `OryUnavailable`, which
+`createMaskError` answers `503 SERVICE_UNAVAILABLE`.
+
+Every question goes through a per-request memo: distinct questions are
+batched into one `POST /relation-tuples/batch/check`, identical ones asked
+once, a failed batch not remembered.
+
+### `@check`, the list-of-lists form — deprecated
+
+`@check(permissions: [[{ namespace, permit, id }]], onDeny, message)` keeps
+working, is validated the same way, and is evaluated in declaration order with
+`@permission` on the same field. Its outer list is OR, its inner list AND. Write
+`@permission` in a new schema; `@check` is planned for removal in a major.
 
 ```graphql
-note(id: ID!): Note!
-	@check(
-		permissions: [[{ namespace: "Note", permit: "view" }]]
-		message: "notes.errors.not-found"
-	)
+note(id: ID!): Note! @check(permissions: [[{ namespace: "Note", permit: "view" }]])
 ```
 
-### What it does not cover, on purpose
+### From a resolver: `requireUser` and `can`
 
-A field that answers a **list** the caller is entitled to. "Which notes may I
-see" is not a check — it is a Keto query (`heldBy(subject)`) folded into the
-database filter before the read. A directive there would have to fetch
-everything and filter after, which makes `totalCount` and the cursors lie.
-Those fields keep their access layer.
+```ts
+import { can, type OryGraphQLContext, requireUser } from '@nxgt/shared-graphql';
+import { CustomException } from '@nxgt/shared-exceptions';
+
+async function archive(_: unknown, { id }: { id: string }, ctx: OryGraphQLContext) {
+	const user = requireUser(ctx); // UNAUTHENTICATED (401) when nobody is calling
+	if (!(await can(ctx, { name: 'edit', type: 'Note', id }))) {
+		throw CustomException.forbidden({ message: 'notes.errors.read-only' });
+	}
+	return notes.archive(id, user.sub);
+}
+```
 
-That access layer stays anyway, and costs nothing: `useKetoChecks` puts a
-per-request loader on the context that **batches** distinct questions into one
-`POST /relation-tuples/batch/check` and **memoises** identical ones. A field
-guarded by `@check(view)` and a service that then asks the same question pay
-for one round trip between them.
+`can` answers Keto's `true` or `false` through the same memo as the
+directives; an outage throws, never answers `false`.
 
-Two mistakes are refused when the schema is built, not when a request arrives:
-an `id` naming neither root, and `permissions: [[]]` — a conjunction over no
-terms is vacuously true, so it would admit everyone while looking guarded.
+### What it does not cover, on purpose
 
-A Keto outage is never a denial: `OryUnavailable` travels up to
-`createMaskError`, which answers 503.
+A field that answers a **list** the caller is entitled to. "Which notes may I
+see" is not a check — it is a Keto query folded into the database filter
+before the read. A directive there would have to fetch everything and filter
+after, which makes `totalCount` and the cursors lie.
 
 ### A shipped directive is not a composed directive
 
 Shipping the SDL is enough for a standalone Yoga schema. It is **not** enough
-for a subgraph that federation composes. The day `@check` is used in `health`
-or `platform`, rover needs both `@composeDirective(name: "@check")` in that
-subgraph and the directive named in the subgraph's own `@link` import list.
-Without them the composition drops it silently — the supergraph SDL comes out
-valid, the field loses its check, and nothing fails.
+for a subgraph that federation composes: that subgraph needs
+`@composeDirective(name: "@permission")` (or `"@check"`) and the directive in
+its own `@link` import list. Without them the composition drops it silently —
+the supergraph SDL comes out valid, the field loses its guard, and nothing
+fails.
+
+## Errors
+
+```ts
+createYoga({ maskedErrors: { maskError: createMaskError(translate) } });
+new ApolloServer({ formatError: createFormatError(translate) });
+```
+
+Under Yoga, `createMaskError` turns a `CustomException` into a `GraphQLError`
+with `extensions { code, http { status } }` — `UNAUTHENTICATED` 401,
+`FORBIDDEN` 403, `NOT_FOUND` 404 — and its translated message; `OryUnavailable`
+into `SERVICE_UNAVAILABLE` 503, recognised even from a second copy of
+`@nxgt/ory-sdk`; and a plain `Error` a resolver threw into the mask message, as
+Yoga's default does.
+
+Under Apollo, `createFormatError` sets the `code` and the translated message
+(and `SERVICE_UNAVAILABLE` for an outage, with `http.status` in `extensions`
+only — `formatError` cannot change the transport status). It masks nothing
+Apollo would not.
 
 ## Plugins and context
 
 | Export | What it does |
 | --- | --- |
-| `useOryAuth(ory)` | Yoga plugin: resolve the caller, set `context.user` |
-| `useKetoChecks(ory)` | Yoga plugin: per-request DataLoader for Keto, and the `@check` transformer |
-| `applyKetoChecks(schema)` | wrap an already-built schema with `@check` |
-| `useAuth()` | Yoga plugin: require a user on the context |
+| `useOryAuth(ory)` | Yoga plugin: resolve the caller through Kratos or Hydra, set `user`, `claims`, `ory` |
+| `useKetoChecks(ory, options?)` | Yoga plugin: the per-request Keto memo, and the `@permission` / `@check` transform |
+| `applyKetoChecks(schema, options?)` | the same transform on an already-built schema |
+| `requireUser(ctx)`, `can(ctx, question)` | the caller or 401; Keto's answer through the memo |
+| `useAuth()` | Yoga plugin: copy `user` and `token` from the request's `extensions` — trust it only behind a gateway that sets them |
 | `extractJwtPlugin` | Apollo plugin: copy `request.extensions.payload` onto `context.jwt` |
 
 `GraphQLBaseContext.user` is `TokenPrincipal` — the caller as the access token
@@ -164,7 +216,10 @@ SDL.
 
 ## Things that bite
 
-- **`@check` on a list field is the wrong tool.** Filter before the read.
+- **`@permission` on a list field is the wrong tool.** Filter before the read.
+- **`useAuth()` reads the request body's `extensions`.** A client that can
+  reach the service directly can set them. Put the service behind the gateway
+  that writes them, or resolve the caller with `useOryAuth(ory)`.
 - **Do not import `graphql-subscriptions` from `graphql-subscriptions`.** Take
   it from this package, same reason mongoose comes from `@nxgt/shared-mongo`.
 - **The sandbox helper is spelled `sandboxExpolorer`.** That is the export

package/dist/directives/check.d.ts

@@ -1,13 +1,13 @@
-import { getDirective } from '@graphql-tools/utils';
-import { type PermissionRequirement, type PermissionTerm } from '@nxgt/ory-sdk';
+import type { PermissionRequirement } from '@nxgt/ory-sdk';
 import type { GraphQLSchema } from 'graphql';
+import { type FieldNode, type ReadOptions } from './scope';
 /**
- * `@check` — the Ory-native counterpart to `@policy`.
+ * `@check` — the list-of-lists form of `@permission`, deprecated in its
+ * favour and kept working.
  *
  * The declaration itself is SDL, in `graphql/directives/check.graphqls`, so it
- * reaches every consumer of `SHARED_SCHEMA_PATH`. This module only reads it.
- * Keeping the two in one place would mean two copies of the same grammar, and
- * the copy nobody edits is the one that goes wrong.
+ * reaches every consumer of `SHARED_SCHEMA_PATH`; `CHECK_DIRECTIVE_SDL` is the
+ * same text as a string, held equal by a spec. This module only reads it.
  */
 export declare const CHECK_DIRECTIVE_NAME = "check";
 export type CheckDenial = 'NOT_FOUND' | 'FORBIDDEN';
@@ -18,23 +18,15 @@ export type CheckArgs = {
     message?: string;
 };
 /**
- * Every `@check` on a field, in declaration order.
+ * Every `@check` on a field, in declaration order, validated.
  *
  * `@check` is repeatable, so this is a list and the order is load-bearing:
  * `view` then `edit` is what turns a denial into 404 for a stranger and 403
- * for a viewer. `getDirective` reads the arguments against the schema's own
- * definition, which is what applies the `id` and `onDeny` defaults — the AST
- * node carries only what was written.
- */
-export declare function readChecks(schema: GraphQLSchema, node: Parameters<typeof getDirective>[1], where: string): CheckArgs[];
-/**
- * Validated here, when the schema is transformed, and not when a request
- * arrives: a path naming neither root is a wiring mistake, and it should stop
- * the server from booting rather than 500 on the one query nobody tried.
+ * for a viewer.
+ *
+ * The `id` and `onDeny` defaults are applied here as well as in the SDL:
+ * graphql 17 no longer hands an input field's default to `getDirective`, and a
+ * term without an id would otherwise refuse the whole schema.
  */
-export declare function assertReadablePath(term: PermissionTerm, where: string): void;
-/** Reads `args.x` / `source.x.y` off a resolver's inputs. */
-export declare function readPath(path: string, source: unknown, args: Record<string, unknown>): unknown;
-/** The ids one term has to clear: one value, or every element of a list. */
-export declare function objectIds(value: unknown): string[];
+export declare function readChecks(schema: GraphQLSchema, node: FieldNode, where: string, options?: ReadOptions): CheckArgs[];
 //# sourceMappingURL=check.d.ts.map

package/dist/directives/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/directives/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAEN,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG;IACvB,WAAW,EAAE,qBAAqB,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EACxC,KAAK,EAAE,MAAM,GACX,SAAS,EAAE,CAeb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,QAMrE;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,OAAO,CAOT;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAKlD"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/directives/check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAkB,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAW,MAAM,SAAS,CAAC;AAGpE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG;IACvB,WAAW,EAAE,qBAAqB,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,EAAE,CAgBb"}

package/dist/directives/deprecation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * How a `@check` mistake that 2.x let boot is reported: a warning at build,
+ * naming the field, that says it becomes a refusal in the next major.
+ * `@permission` is new, so the same mistake there throws.
+ */
+export declare function warnCheckMistake(message: string): void;
+//# sourceMappingURL=deprecation.d.ts.map

package/dist/directives/deprecation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.d.ts","sourceRoot":"","sources":["../../src/directives/deprecation.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,QAI/C"}

package/dist/directives/index.d.ts

@@ -1,3 +1,8 @@
 export * from './check';
 export * from './federation';
+export { assertReadablePath, objectIds, readPath } from './paths';
+export * from './permission';
+export * from './requirements';
+export type { ReadOptions } from './scope';
+export * from './sdl';
 //# sourceMappingURL=index.d.ts.map

package/dist/directives/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/directives/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/directives/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAClE,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,cAAc,OAAO,CAAC"}

package/dist/directives/paths.d.ts

@@ -0,0 +1,20 @@
+import type { PermissionTerm } from '@nxgt/ory-sdk';
+/** The id a term reads when it names none. */
+export declare const DEFAULT_ID_PATH = "args.id";
+/**
+ * Validated when the schema is transformed, and not when a request arrives: a
+ * path naming no root is a wiring mistake, and it should stop the server from
+ * booting rather than 500 on the one query nobody tried.
+ */
+export declare function assertReadablePath(term: PermissionTerm, where: string): void;
+/**
+ * `args.<name>` must name an argument the field declares. Graphql-js never
+ * puts an undeclared argument on `args`, so a typo here resolves no object on
+ * every request — refused at build instead, naming the arguments there are.
+ */
+export declare function assertDeclaredArgument(term: PermissionTerm, argumentNames: readonly string[], where: string): void;
+/** Reads `args.x` / `parent.x.y` / `source.x.y` off a resolver's inputs. */
+export declare function readPath(path: string, source: unknown, args: Record<string, unknown>): unknown;
+/** The ids one term has to clear: one value, or every element of a list. */
+export declare function objectIds(value: unknown): string[];
+//# sourceMappingURL=paths.d.ts.map

package/dist/directives/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/directives/paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAYpD,8CAA8C;AAC9C,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,QAMrE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,KAAK,EAAE,MAAM,QAUb;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,OAAO,CAOT;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAKlD"}

package/dist/directives/permission.d.ts

@@ -0,0 +1,25 @@
+import type { GraphQLSchema } from 'graphql';
+import type { CheckArgs, CheckDenial } from './check';
+import { type FieldNode, type ReadOptions } from './scope';
+/**
+ * `@permission(name:, type:, id:, onDeny:, message:)` — one Keto question per
+ * directive, the vocabulary `@nxgt/janus-graphql` uses. Declared in
+ * `graphql/directives/permission.graphqls` and `PERMISSION_DIRECTIVE_SDL`.
+ */
+export declare const PERMISSION_DIRECTIVE_NAME = "permission";
+export type PermissionDenial = CheckDenial;
+/** One `@permission` as written, after its defaults. */
+export type PermissionArgs = {
+    name: string;
+    type: string;
+    id: string;
+    onDeny: PermissionDenial;
+    message?: string;
+};
+/**
+ * Every `@permission` on a field, in declaration order, validated, each as the
+ * one-term requirement `@check` would spell `[[{ namespace: type, permit:
+ * name, id }]]` — so the transform answers both through one path.
+ */
+export declare function readPermissions(schema: GraphQLSchema, node: FieldNode, where: string, options?: ReadOptions): CheckArgs[];
+//# sourceMappingURL=permission.d.ts.map

package/dist/directives/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/directives/permission.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAW,MAAM,SAAS,CAAC;AAGpE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE3C,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,EAAE,CAab"}

package/dist/directives/requirements.d.ts

@@ -0,0 +1,14 @@
+import type { GraphQLSchema } from 'graphql';
+import { type CheckArgs } from './check';
+import type { FieldNode, ReadOptions } from './scope';
+/**
+ * Every `@check` and `@permission` on a field, validated, in the order they
+ * are written — across the two names, so a field migrating one directive at a
+ * time keeps its 404-then-403 ladder.
+ *
+ * `getDirective` answers per name, so the interleaving is read back off the
+ * field's AST. A field built without one (a schema made in code) has no order
+ * to keep across names, and gets its `@check`s first.
+ */
+export declare function readRequirements(schema: GraphQLSchema, node: FieldNode, where: string, options?: ReadOptions): CheckArgs[];
+//# sourceMappingURL=requirements.d.ts.map

package/dist/directives/requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../../src/directives/requirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAwB,KAAK,SAAS,EAAc,MAAM,SAAS,CAAC;AAE3E,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,EAAE,CAeb"}

package/dist/directives/scope.d.ts

@@ -0,0 +1,19 @@
+import type { getDirective } from '@graphql-tools/utils';
+import type { RequirementScope } from './validate';
+/** A field definition or a field config — whatever `getDirective` reads. */
+export type FieldNode = Parameters<typeof getDirective>[1];
+/** What a schema may add to the build-time checks of `@check` and `@permission`. */
+export type ReadOptions = {
+    /**
+     * The namespaces of the stack's OPL document. When given, a `type` or
+     * `namespace` outside it is refused at build.
+     */
+    namespaces?: readonly string[];
+};
+/**
+ * The scope a field's requirements are validated in: the message prefix, the
+ * arguments the field declares — read from a field config's `args` map or a
+ * definition node's `arguments` list — and the known namespaces.
+ */
+export declare function scopeOf(node: FieldNode, where: string, options: ReadOptions): RequirementScope;
+//# sourceMappingURL=scope.d.ts.map

package/dist/directives/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/directives/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3D,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,OAAO,CACtB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAClB,gBAAgB,CAMlB"}

package/dist/directives/sdl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The directive declarations `graphql/directives/*.graphqls` ship, as strings,
+ * for a schema assembled in code rather than loaded from `SHARED_SCHEMA_PATH`
+ * — an edge runtime with no file system, or a test.
+ *
+ * The files are the source; these are copies of their declarations, without
+ * the `#` comments, and `sdl.spec.ts` holds each equal to its file once both
+ * are parsed and printed. Edit the file, then this.
+ */
+/** `@check`, its `CheckPermission` input and its `CheckDenial` enum. */
+export declare const CHECK_DIRECTIVE_SDL = "\"\"\"\nOne question, with the object left as a path instead of a value.\n\"\"\"\ninput CheckPermission {\n\t\"\"\"\n\tThe Keto namespace, e.g. \"Note\" \u2014 from the stack's OPL document.\n\t\"\"\"\n\tnamespace: String!\n\n\t\"\"\"\n\tThe permit asked of it, e.g. \"view\". A plain relation works too; Keto\n\tanswers `false`, not an error, for a name it does not know.\n\t\"\"\"\n\tpermit: String!\n\n\t\"\"\"\n\tWhere the object id is read: `args.<path>`, or `parent.<path>` /\n\t`source.<path>` (the same root under two names), dotted paths allowed. A value that turns out to be a LIST requires the permit on every\n\telement \u2014 that is what a mutation taking `ids: [ID!]!` means.\n\t\"\"\"\n\tid: String = \"args.id\"\n}\n\n\"\"\"\nWhat a denial looks like from outside.\n\"\"\"\nenum CheckDenial {\n\t\"\"\"\n\tThe same answer as for an id that never existed, so ids cannot be probed.\n\tThe default, and the one to keep unless the caller already knows the object\n\tis there.\n\t\"\"\"\n\tNOT_FOUND\n\n\t\"\"\"\n\tFor a second check on an object the caller can already see: a viewer asked\n\tto edit already knows it exists, and \"you may not change it\" is honest.\n\t\"\"\"\n\tFORBIDDEN\n}\n\n\"\"\"\nDeprecated: write `@permission(name:, type:)` in a new schema \u2014 one Keto\nquestion per directive, repeated for AND, with OR kept in the Keto model. This\nform keeps working and is evaluated in declaration order with @permission.\n\nThe permission a field requires, in disjunctive normal form: the OUTER list is\nOR, the INNER list is AND. `[[A, B], [C]]` reads \"(A and B) or C\" \u2014 the same\nshape `@policy(policies: [[\"ADMIN\"]])` uses.\n\nRepeatable, and evaluated in declaration order, each with its own `onDeny`.\nThat is how the 404-then-403 ladder is written:\n\n    updateNote(id: ID!, input: UpdateNoteInput!): Note!\n      @check(permissions: [[{ namespace: \"Note\", permit: \"view\" }]])\n      @check(permissions: [[{ namespace: \"Note\", permit: \"edit\" }]], onDeny: FORBIDDEN)\n\nNOT for a field that answers a LIST the caller is entitled to. \"Which notes may\nI see\" is not a check, it is a Keto query folded into the database filter\nbefore the read. A directive there would have to fetch everything and filter\nafter, which makes `totalCount` and the cursors lie.\n\"\"\"\ndirective @check(\n\tpermissions: [[CheckPermission!]!]!\n\tonDeny: CheckDenial! = NOT_FOUND\n\n\t\"\"\"\n\tThe i18n key the denial carries, e.g. \"notes.errors.not-found\". Defaults to\n\t`errors.not-found` / `errors.insufficient-permissions`, the shared keys.\n\n\tSet it whenever the API's own service layer answers the same refusal with a\n\tdomain message. Two layers guard these fields \u2014 the directive, and the\n\t`require<M>Access` the service calls \u2014 and if they word the same 404\n\tdifferently, the wording tells a caller WHICH one refused: a generic message\n\tmeans \"you may not\", a domain one means \"it is gone\". That is precisely the\n\tdistinction NOT_FOUND exists to hide.\n\t\"\"\"\n\tmessage: String\n) repeatable on FIELD_DEFINITION\n";
+/** `@permission` and its `PermissionDenial` enum. */
+export declare const PERMISSION_DIRECTIVE_SDL = "\"\"\"\nWhat a refused @permission looks like from outside.\n\"\"\"\nenum PermissionDenial {\n\t\"\"\"\n\tThe same answer as for an id that never existed, so ids cannot be probed.\n\tThe default.\n\t\"\"\"\n\tNOT_FOUND\n\n\t\"\"\"\n\tFor a permission asked of an object the caller can already see: a viewer\n\tasked to edit already knows it exists, and \"you may not change it\" is\n\thonest.\n\t\"\"\"\n\tFORBIDDEN\n}\n\n\"\"\"\nThe permission a field requires: the caller must hold the permit `name` on the\n`type` object whose id `id` points at.\n\nRepeatable, and repeated ones are AND, evaluated in declaration order \u2014 the\n404-then-403 ladder:\n\n    updateNote(id: ID!, input: UpdateNoteInput!): Note!\n      @permission(name: \"view\", type: \"Note\")\n      @permission(name: \"edit\", type: \"Note\", onDeny: FORBIDDEN)\n\nNOT for a field that answers a LIST the caller is entitled to: fold a Keto\nquery into the database filter before the read instead.\n\"\"\"\ndirective @permission(\n\t\"\"\"\n\tThe permit asked of Keto, e.g. \"view\". A plain relation works too; Keto\n\tanswers `false`, not an error, for a name it does not know.\n\t\"\"\"\n\tname: String!\n\n\t\"\"\"\n\tThe Keto namespace, e.g. \"Note\" \u2014 from the stack's OPL document.\n\t\"\"\"\n\ttype: String!\n\n\t\"\"\"\n\tWhere the object id is read: `args.<path>` or `parent.<path>`, dotted\n\tpaths allowed, `args.id` when omitted. A value that turns out to be a LIST\n\trequires the permit on every element.\n\t\"\"\"\n\tid: String\n\n\tonDeny: PermissionDenial! = NOT_FOUND\n\n\t\"\"\"\n\tThe i18n key the denial carries, e.g. \"notes.errors.not-found\". Defaults to\n\t`errors.not-found` / `errors.insufficient-permissions`, the shared keys.\n\tSet it when the service layer words the same refusal with a domain message,\n\tso the wording does not tell a caller which layer refused.\n\t\"\"\"\n\tmessage: String\n) repeatable on FIELD_DEFINITION\n";
+/** Both, for `createSchema({ typeDefs: [KETO_DIRECTIVES_SDL, …] })`. */
+export declare const KETO_DIRECTIVES_SDL = "\"\"\"\nOne question, with the object left as a path instead of a value.\n\"\"\"\ninput CheckPermission {\n\t\"\"\"\n\tThe Keto namespace, e.g. \"Note\" \u2014 from the stack's OPL document.\n\t\"\"\"\n\tnamespace: String!\n\n\t\"\"\"\n\tThe permit asked of it, e.g. \"view\". A plain relation works too; Keto\n\tanswers `false`, not an error, for a name it does not know.\n\t\"\"\"\n\tpermit: String!\n\n\t\"\"\"\n\tWhere the object id is read: `args.<path>`, or `parent.<path>` /\n\t`source.<path>` (the same root under two names), dotted paths allowed. A value that turns out to be a LIST requires the permit on every\n\telement \u2014 that is what a mutation taking `ids: [ID!]!` means.\n\t\"\"\"\n\tid: String = \"args.id\"\n}\n\n\"\"\"\nWhat a denial looks like from outside.\n\"\"\"\nenum CheckDenial {\n\t\"\"\"\n\tThe same answer as for an id that never existed, so ids cannot be probed.\n\tThe default, and the one to keep unless the caller already knows the object\n\tis there.\n\t\"\"\"\n\tNOT_FOUND\n\n\t\"\"\"\n\tFor a second check on an object the caller can already see: a viewer asked\n\tto edit already knows it exists, and \"you may not change it\" is honest.\n\t\"\"\"\n\tFORBIDDEN\n}\n\n\"\"\"\nDeprecated: write `@permission(name:, type:)` in a new schema \u2014 one Keto\nquestion per directive, repeated for AND, with OR kept in the Keto model. This\nform keeps working and is evaluated in declaration order with @permission.\n\nThe permission a field requires, in disjunctive normal form: the OUTER list is\nOR, the INNER list is AND. `[[A, B], [C]]` reads \"(A and B) or C\" \u2014 the same\nshape `@policy(policies: [[\"ADMIN\"]])` uses.\n\nRepeatable, and evaluated in declaration order, each with its own `onDeny`.\nThat is how the 404-then-403 ladder is written:\n\n    updateNote(id: ID!, input: UpdateNoteInput!): Note!\n      @check(permissions: [[{ namespace: \"Note\", permit: \"view\" }]])\n      @check(permissions: [[{ namespace: \"Note\", permit: \"edit\" }]], onDeny: FORBIDDEN)\n\nNOT for a field that answers a LIST the caller is entitled to. \"Which notes may\nI see\" is not a check, it is a Keto query folded into the database filter\nbefore the read. A directive there would have to fetch everything and filter\nafter, which makes `totalCount` and the cursors lie.\n\"\"\"\ndirective @check(\n\tpermissions: [[CheckPermission!]!]!\n\tonDeny: CheckDenial! = NOT_FOUND\n\n\t\"\"\"\n\tThe i18n key the denial carries, e.g. \"notes.errors.not-found\". Defaults to\n\t`errors.not-found` / `errors.insufficient-permissions`, the shared keys.\n\n\tSet it whenever the API's own service layer answers the same refusal with a\n\tdomain message. Two layers guard these fields \u2014 the directive, and the\n\t`require<M>Access` the service calls \u2014 and if they word the same 404\n\tdifferently, the wording tells a caller WHICH one refused: a generic message\n\tmeans \"you may not\", a domain one means \"it is gone\". That is precisely the\n\tdistinction NOT_FOUND exists to hide.\n\t\"\"\"\n\tmessage: String\n) repeatable on FIELD_DEFINITION\n\n\"\"\"\nWhat a refused @permission looks like from outside.\n\"\"\"\nenum PermissionDenial {\n\t\"\"\"\n\tThe same answer as for an id that never existed, so ids cannot be probed.\n\tThe default.\n\t\"\"\"\n\tNOT_FOUND\n\n\t\"\"\"\n\tFor a permission asked of an object the caller can already see: a viewer\n\tasked to edit already knows it exists, and \"you may not change it\" is\n\thonest.\n\t\"\"\"\n\tFORBIDDEN\n}\n\n\"\"\"\nThe permission a field requires: the caller must hold the permit `name` on the\n`type` object whose id `id` points at.\n\nRepeatable, and repeated ones are AND, evaluated in declaration order \u2014 the\n404-then-403 ladder:\n\n    updateNote(id: ID!, input: UpdateNoteInput!): Note!\n      @permission(name: \"view\", type: \"Note\")\n      @permission(name: \"edit\", type: \"Note\", onDeny: FORBIDDEN)\n\nNOT for a field that answers a LIST the caller is entitled to: fold a Keto\nquery into the database filter before the read instead.\n\"\"\"\ndirective @permission(\n\t\"\"\"\n\tThe permit asked of Keto, e.g. \"view\". A plain relation works too; Keto\n\tanswers `false`, not an error, for a name it does not know.\n\t\"\"\"\n\tname: String!\n\n\t\"\"\"\n\tThe Keto namespace, e.g. \"Note\" \u2014 from the stack's OPL document.\n\t\"\"\"\n\ttype: String!\n\n\t\"\"\"\n\tWhere the object id is read: `args.<path>` or `parent.<path>`, dotted\n\tpaths allowed, `args.id` when omitted. A value that turns out to be a LIST\n\trequires the permit on every element.\n\t\"\"\"\n\tid: String\n\n\tonDeny: PermissionDenial! = NOT_FOUND\n\n\t\"\"\"\n\tThe i18n key the denial carries, e.g. \"notes.errors.not-found\". Defaults to\n\t`errors.not-found` / `errors.insufficient-permissions`, the shared keys.\n\tSet it when the service layer words the same refusal with a domain message,\n\tso the wording does not tell a caller which layer refused.\n\t\"\"\"\n\tmessage: String\n) repeatable on FIELD_DEFINITION\n";
+//# sourceMappingURL=sdl.d.ts.map

package/dist/directives/sdl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdl.d.ts","sourceRoot":"","sources":["../../src/directives/sdl.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,ohGA+E/B,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,u5DA6DpC,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,w6JAAwD,CAAC"}

package/dist/directives/validate.d.ts

@@ -0,0 +1,29 @@
+import { type PermissionRequirement } from '@nxgt/ory-sdk';
+/**
+ * What a requirement is checked against when the schema is built.
+ *
+ * `namespaces` is optional: without it any namespace is taken on trust, as
+ * before. With it — the namespaces of the stack's OPL document — a misspelt
+ * `type` stops the server from booting instead of answering `false` for ever,
+ * which Keto does, without an error, for a namespace it does not know.
+ */
+export type RequirementScope = {
+    /** `@check on Query.note` — the directive and the field, for the message. */
+    where: string;
+    argumentNames: readonly string[];
+    namespaces?: readonly string[];
+    /**
+     * Set for `@check` alone: a mistake it used to let boot — an argument the
+     * field does not declare — is reported here instead of thrown, so a 2.x
+     * schema that booted still boots. It becomes a refusal in the next major.
+     */
+    lenient?: (message: string) => void;
+};
+/**
+ * Every mistake a requirement can carry that is visible without a request, as
+ * a `TypeError` naming the field: an empty requirement or group (`[[]]` admits
+ * everyone), a path naming no root, an argument the field does not declare,
+ * and a namespace the model does not have.
+ */
+export declare function assertRequirementShape(permissions: PermissionRequirement, scope: RequirementScope): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/directives/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/directives/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG9E;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,qBAAqB,EAClC,KAAK,EAAE,gBAAgB,QAmBvB"}