@nxgt/shared-graphql 2.0.1 → 3.0.0

package/README.md

@@ -4,15 +4,26 @@ The GraphQL layer: Yoga + Hono wiring, the federation subgraph builder, shared
 scalars and directives, dataloaders, subscriptions over Redis, upload handling,
 and the SDL every service merges into its own schema.
 
+**Upgrading from 2.x?** Read [Migrating to 3.0](./docs/guide/migrating-to-3.md)
+— the caller is no longer read from a request body a client writes, `@check`
+is gone, and denials are `GraphQLError`s.
+
 ## Install
 
 ```bash
 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.9.0 \|\| ^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 <1` | `useOryAuth`, `useKetoChecks`, `can`; a 1.x is admitted once it is tested |
+| `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 +42,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
@@ -46,116 +61,201 @@ schema: ['./src/**/*.graphqls', SHARED_SCHEMA_PATH],
 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
-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.
+`SHARED_TYPE_DEFS` is a string of the shared directives
+(`@authenticated(type:)`, `@policy`, `@shareable`, `@link`) plus empty root
+types. `@permission` is not in it: it lives in `graphql/directives/`, so a
+subgraph that builds through `buildSubgraphSchema` and never loads
+`SHARED_TYPE_DEFS` still sees it through `SHARED_SCHEMA_PATH`. For a schema
+assembled in code, the declarations ship as strings —
+`PERMISSION_DIRECTIVE_SDL` (also exported as `KETO_DIRECTIVES_SDL`), held
+equal to its file by a spec, and `AUTHENTICATED_DIRECTIVE_SDL`, which has no
+file: it lives in `SHARED_TYPE_DEFS` and in this string only.
+
+```ts
+import { AUTHENTICATED_DIRECTIVE_SDL, PERMISSION_DIRECTIVE_SDL } from '@nxgt/shared-graphql';
+
+createSchema({ typeDefs: [AUTHENTICATED_DIRECTIVE_SDL, PERMISSION_DIRECTIVE_SDL, typeDefs], resolvers });
+```
 
 `buildSubgraphSchema` wraps Apollo's builder and prunes unused types.
 
-## `@check` — the permission a field requires
+## Who is calling
+
+The caller comes from a source the server verified — never from the request
+body alone.
+
+```ts
+// An API that authenticates its own callers: Kratos session, Hydra token.
+createYoga({ plugins: [useOryAuth(ory), useAuthenticated()] });
+
+// A subgraph behind a gateway that resolved the caller and put it in `extensions`.
+const trustedGateway = gatewaySecret({ secret: process.env.GATEWAY_SECRET! });
+createYoga({ plugins: [useAuth({ trustedGateway }), useAuthenticated()] });
+new ApolloServer({ plugins: [extractJwtPlugin({ trustedGateway })] });
+```
+
+- `useOryAuth(ory)` resolves the caller through Kratos or Hydra, and sets
+  `user`, `claims`, `token` and `ory`. An Ory outage is a 503, never an
+  anonymous caller.
+- `useAuth()` and `extractJwtPlugin()` read the caller a gateway put in the
+  GraphQL request's `extensions` — **only** for a request `trustedGateway`
+  vouches for. `gatewaySecret({ secret, header? })` holds for a request whose
+  `x-gateway-secret` header carries the secret (compared in constant time,
+  16 characters at least). Anything else leaves the context without a caller.
+  Without a `trustedGateway`, both throw when the server starts.
+
+### `@authenticated(type: [String!])`
+
+```graphql
+me: User @authenticated
+webhooks: [Webhook!]! @authenticated(type: ["token"])
+type Staff @authenticated(type: ["session"]) { … }
+```
+
+`useAuthenticated(options?)` enforces it: no caller is `UNAUTHENTICATED`
+(401), a caller of a type `type:` does not name is `FORBIDDEN` (403). The type
+is Ory's `kind` — `session` or `token` — or `user.tokenType` without Ory;
+`useAuthenticated({ types: [...CALLER_TYPES, 'service'] })` names other
+values. The field's, its type's and its interfaces' directives are AND-ed; a
+scalar's or an enum's guards every field returning it; a subscription is
+refused before its stream opens. Refused at build, naming where the directive
+sits: `type: []`, an unknown type, and restrictions with nothing in common.
+
+Federation declares `@authenticated` with no argument, and a subgraph imports
+that declaration. `useAuthenticated` reads that shape as "any caller", so keep
+federation's declaration in a subgraph; `type:` is for the schemas this
+package's `SHARED_TYPE_DEFS` builds. Details: [the authentication
+guide](./docs/guide/authentication.md).
+
+## `@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'] })]
 ```
 
-`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), a guard on an interface field,
+where no resolver runs, and a `@check` — removed in 3.0 — left in the schema.
+
+`@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.
+
+### From a resolver: `requireUser` and `can`
 
-```graphql
-note(id: ID!): Note!
-	@check(
-		permissions: [[{ namespace: "Note", permit: "view" }]]
-		message: "notes.errors.not-found"
-	)
+```ts
+import { can, denial, type OryGraphQLContext, requireUser } from '@nxgt/shared-graphql';
+import { ErrorCode } 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 denial(ErrorCode.Forbidden, 'notes.errors.read-only');
+	}
+	return notes.archive(id, user.sub);
+}
 ```
 
+`can` answers Keto's `true` or `false` through the same memo as the
+directives; an outage throws, never answers `false`.
+
 ### What it does not cover, on purpose
 
 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.
+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
 
-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.
+Shipping the SDL is enough for a standalone Yoga schema. It is **not** enough
+for a subgraph that federation composes: that subgraph needs
+`@composeDirective(name: "@permission")` 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.
 
-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.
+## Errors
 
-A Keto outage is never a denial: `OryUnavailable` travels up to
-`createMaskError`, which answers 503.
+A denial — from `@permission`, `@authenticated`, `requireUser` or `can`, or
+your own `denial(code, message?)` — is a `GraphQLError` with
+`extensions { code, http { status } }`: `UNAUTHENTICATED` 401, `FORBIDDEN` 403,
+`NOT_FOUND` 404. Any Yoga or Apollo server answers it with that status. To
+translate its message and map the rest, register:
 
-### A shipped directive is not a composed directive
+```ts
+createYoga({ maskedErrors: { maskError: createMaskError(translate) } });
+new ApolloServer({ formatError: createFormatError(translate) });
+```
 
-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.
+Under Yoga, `createMaskError` translates a denial's key with your
+`translate`; turns a `CustomException` into a `GraphQLError` with its code,
+status and 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 |
-| `extractJwtPlugin` | Apollo plugin: copy `request.extensions.payload` onto `context.jwt` |
+| `useOryAuth(ory)` | Yoga plugin: resolve the caller through Kratos or Hydra, set `user`, `claims`, `token`, `ory` |
+| `useAuth({ trustedGateway })` | Yoga plugin: the caller a trusted gateway put in `extensions` — `user`, `token` |
+| `extractJwtPlugin({ trustedGateway })` | Apollo plugin: the payload a trusted gateway put in `extensions.payload`, on `context.jwt` |
+| `gatewaySecret({ secret, header? })` | the stock `trustedGateway`: a shared secret in a header |
+| `useAuthenticated(options?)` | Yoga plugin: enforce `@authenticated(type:)`; `CALLER_TYPES` is the default `types` |
+| `applyAuthenticated(schema, options?)` | the same transform on an already-built schema |
+| `useKetoChecks(ory, options?)` | Yoga plugin: the per-request Keto memo, and the `@permission` 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 |
+| `denial(code, message?)` | a refusal as a `GraphQLError` with its status |
 
 `GraphQLBaseContext.user` is `TokenPrincipal` — the caller as the access token
 describes them (`sub`, `uid`, `scope`). It is not `Principal`, which is the
 header-derived shape used by the REST services.
 
 `createYogaHono` / `honoYoga` (from this package's integrations) mount Yoga on
-Hono. `sandboxExpolorer` serves Apollo Sandbox. Subscriptions go over Redis
+Hono. `sandboxExplorer` serves Apollo Sandbox. Subscriptions go over Redis
 (`graphql-subscriptions` is re-exported). `DataLoader` is re-exported so a
 subgraph does not take a second copy.
 
@@ -164,11 +264,26 @@ 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()` without the gateway's header reads no caller.** A gateway
+  that does not send `x-gateway-secret` on every subgraph request makes every
+  caller anonymous. Send it from the gateway, not from clients.
+- **An object type's `@authenticated` guards its fields, not the field that
+  returns it** (a scalar's or an enum's does guard the fields returning it).
+  Put the directive on the field too when the lookup itself must not run for
+  an anonymous caller.
 - **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
-  name. A corrected spelling is a breaking change, not a typo fix in the
-  consumer.
 - **`stx-sdk` is required.** Unlike `@nxgt/security`, this package does not
   mark it optional.
+
+## Documentation
+
+| Page | Read it when |
+| --- | --- |
+| [Migrating to 3.0](./docs/guide/migrating-to-3.md) | you upgrade from 2.x |
+| [Authentication](./docs/guide/authentication.md) | you wire `useOryAuth`, `useAuth` behind a gateway, or `@authenticated` |
+| [Permissions](./docs/guide/permissions.md) | you guard a field with `@permission`, or ask Keto from a resolver |
+| [Errors](./docs/guide/errors.md) | you decide what a client receives, or write your own mask |
+| [Troubleshooting](./docs/troubleshooting.md) | you have an error message in hand |
+| [Roadmap](./docs/roadmap.md) | you want to know what is next |

package/dist/directives/authenticated.d.ts

@@ -0,0 +1,42 @@
+import type { GraphQLSchema } from 'graphql';
+import type { FieldNode } from './scope';
+export declare const AUTHENTICATED_DIRECTIVE_NAME = "authenticated";
+/**
+ * The kinds of caller `@authenticated(type:)` can name by default: Ory's
+ * `OryPrincipal.kind` — a Kratos `session`, or an OAuth2 access `token`
+ * (introspected by Hydra, whether a person's or a `client_credentials` one).
+ */
+export declare const CALLER_TYPES: readonly ["session", "token"];
+export type AuthenticatedOptions = {
+    /**
+     * Every value a `type:` may name, when the caller's type is not Ory's
+     * `kind` — `TokenPrincipal.tokenType` behind a gateway, say. A `type`
+     * outside it is refused at build. `CALLER_TYPES` by default.
+     */
+    types?: readonly string[];
+};
+/**
+ * What the `@authenticated`s that apply to one field demand together: a
+ * caller, and — when `types` is set — one of those types. Every directive
+ * that applies must hold, so `types` is their intersection.
+ */
+export type CallerRequirement = {
+    types?: readonly string[];
+};
+/**
+ * The `@authenticated` on a field, a type or an interface, read and
+ * validated: `null` when there is none, `{}` for any caller, `{ types }` for
+ * a caller of one of them.
+ *
+ * Federation declares `@authenticated` with no argument. A schema that
+ * imports that declaration has no `type` to read, and every `@authenticated`
+ * in it means "any caller" — the shape is accepted as it is.
+ */
+export declare function readAuthenticated(schema: GraphQLSchema, node: FieldNode, where: string, known: readonly string[]): CallerRequirement | null;
+/**
+ * Every requirement that applies to one field, AND-ed: a caller when any
+ * applies, and the types all of them admit. Refused at build when they admit
+ * no type in common — no request could pass.
+ */
+export declare function combineRequirements(found: readonly (CallerRequirement | null)[], where: string): CallerRequirement | null;
+//# sourceMappingURL=authenticated.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated.d.ts","sourceRoot":"","sources":["../../src/directives/authenticated.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,YAAY,+BAAgC,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,GACtB,iBAAiB,GAAG,IAAI,CAmB1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAAE,EAC5C,KAAK,EAAE,MAAM,GACX,iBAAiB,GAAG,IAAI,CAc1B"}

package/dist/directives/federation.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Federation's own directive declarations, as a subgraph imports them.
+ * `@authenticated` keeps federation's shape — no argument — which
+ * `useAuthenticated` reads as "any caller". `AUTHENTICATED_DIRECTIVE_SDL`, in
+ * `SHARED_TYPE_DEFS`, is the one with `type:`.
+ */
 export declare const FEDERATION_DIRECTIVES = "\ndirective @external on FIELD_DEFINITION | OBJECT\ndirective @requires(fields: FieldSet!) on FIELD_DEFINITION\ndirective @provides(fields: FieldSet!) on FIELD_DEFINITION\ndirective @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE\ndirective @shareable repeatable on OBJECT | FIELD_DEFINITION\ndirective @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION\ndirective @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION\ndirective @override(from: String!) on FIELD_DEFINITION\ndirective @composeDirective(name: String!) repeatable on SCHEMA\ndirective @interfaceObject on OBJECT\ndirective @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM\n";
 //# sourceMappingURL=federation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../src/directives/federation.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,45BAYjC,CAAC"}
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../src/directives/federation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,45BAYjC,CAAC"}

package/dist/directives/index.d.ts

@@ -1,3 +1,7 @@
-export * from './check';
+export { AUTHENTICATED_DIRECTIVE_NAME, type AuthenticatedOptions, CALLER_TYPES, } from './authenticated';
 export * from './federation';
+export { assertReadablePath, objectIds, readPath } from './paths';
+export * from './permission';
+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,OAAO,EACN,4BAA4B,EAC5B,KAAK,oBAAoB,EACzB,YAAY,GACZ,MAAM,iBAAiB,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAClE,cAAc,cAAc,CAAC;AAC7B,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,39 @@
+import type { PermissionRequirement } from '@nxgt/ory-sdk';
+import type { GraphQLSchema } from 'graphql';
+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 = 'NOT_FOUND' | 'FORBIDDEN';
+/** One `@permission` as written, after its defaults. */
+export type PermissionArgs = {
+    name: string;
+    type: string;
+    id: string;
+    onDeny: PermissionDenial;
+    message?: string;
+};
+/**
+ * One `@permission` as the transform answers it: the one-term requirement
+ * `[[{ namespace: type, permit: name, id }]]` that `evaluateRequirement`
+ * takes, its denial, and its i18n key.
+ */
+export type FieldPermission = {
+    permissions: PermissionRequirement;
+    onDeny: PermissionDenial;
+    /** i18n key; the shared `errors.*` one when the field does not say. */
+    message?: string;
+};
+/**
+ * Every `@permission` on a field, in declaration order, validated.
+ *
+ * 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.
+ * The `id` and `onDeny` defaults are applied here as well as in the SDL, which
+ * graphql 17 does not always hand to `getDirective`.
+ */
+export declare function readPermissions(schema: GraphQLSchema, node: FieldNode, where: string, options?: ReadOptions): FieldPermission[];
+//# 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,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,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,GAAG,WAAW,CAAC;AAEzD,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,MAAM,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE,qBAAqB,CAAC;IACnC,MAAM,EAAE,gBAAgB,CAAC;IACzB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,eAAe,EAAE,CAanB"}

package/dist/directives/removed-check.d.ts

@@ -0,0 +1,15 @@
+import type { GraphQLSchema } from 'graphql';
+import type { FieldNode } from './scope';
+/**
+ * `@check`, the list-of-lists form, was removed in 3.0. This package no longer
+ * ships its declaration, so a schema that still writes one either fails to
+ * build (`Unknown directive "@check"`) or declares it itself — and then the
+ * transform, which no longer reads it, would leave the field open in silence.
+ *
+ * So a field carrying a `@check` whose declaration has `permissions` — the
+ * shape 2.x shipped — is refused when the schema is built, naming the field
+ * and the rewrite. A `@check` of another shape is the schema's own and is left
+ * alone, as a foreign `@permission` is.
+ */
+export declare function refuseRemovedCheck(schema: GraphQLSchema, node: FieldNode, where: string): void;
+//# sourceMappingURL=removed-check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"removed-check.d.ts","sourceRoot":"","sources":["../../src/directives/removed-check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,QAQb"}

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 `@permission`. */
+export type ReadOptions = {
+    /**
+     * The namespaces of the stack's OPL document. When given, a `type`
+     * 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,uEAAuE;AACvE,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,26 @@
+/**
+ * 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.
+ */
+/** `@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";
+/**
+ * Every directive `useKetoChecks` answers, for
+ * `createSchema({ typeDefs: [KETO_DIRECTIVES_SDL, …] })`. Since `@check` was
+ * removed in 3.0, that is `@permission` alone.
+ */
+export declare const KETO_DIRECTIVES_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";
+/**
+ * `@authenticated`, with the `type:` `useAuthenticated` reads: any caller
+ * without it, a caller of one of the types with it. Part of
+ * `SHARED_TYPE_DEFS`, and not in `graphql/`: a federation subgraph loads
+ * `SHARED_SCHEMA_PATH` and imports federation's own `@authenticated`, which
+ * takes no argument — a shape `useAuthenticated` reads as "any caller".
+ */
+export declare const AUTHENTICATED_DIRECTIVE_SDL = "\"\"\"\nA signed-in caller \u2014 of one of the types `type` names, when it names some.\n\"\"\"\ndirective @authenticated(\n\t\"\"\"\n\tThe kinds of caller admitted: \"session\" or \"token\" by default. Any caller\n\twhen omitted.\n\t\"\"\"\n\ttype: [String!]\n) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM\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,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,u5DA6DpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,u5DAA2B,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,sUAUvC,CAAC"}

package/dist/directives/validate.d.ts

@@ -0,0 +1,23 @@
+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. 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 = {
+    /** `@permission on Query.note` — the directive and the field, for the message. */
+    where: string;
+    argumentNames: readonly string[];
+    namespaces?: readonly string[];
+};
+/**
+ * Every mistake a requirement can carry that is visible without a request, as
+ * a `TypeError` naming the field: an empty name or type, 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,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,qBAAqB,EAClC,KAAK,EAAE,gBAAgB,QAmBvB"}