@nxgt/shared-graphql 2.1.0 → 3.0.0

package/dist/integrations/hono.d.ts

@@ -1,7 +1,7 @@
 import type { YogaInitialContext, YogaServerInstance } from 'graphql-yoga';
 import { Hono } from 'hono';
-import { type RenderSandboxOptions } from '../utils';
-export declare function sandboxExpolorer(options: RenderSandboxOptions): import("hono").MiddlewareHandler<any, string, {}, Response>;
+import { type RenderSandboxOptions } from '../utils/sandbox';
+export declare function sandboxExplorer(options: RenderSandboxOptions): import("hono").MiddlewareHandler<any, string, {}, Response>;
 type HonoYogaOptions = {
     sandbox?: RenderSandboxOptions & {
         endpoint?: string;

package/dist/integrations/hono.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/integrations/hono.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,UAAU,CAAC;AAEpE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,+DAI7D;AAED,KAAK,eAAe,GAAG;IACtB,OAAO,CAAC,EAAE,oBAAoB,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD,CAAC;AAEF,wBAAgB,QAAQ,CACvB,aAAa,SAAS,OAAO,CAAC,kBAAkB,CAAC,EACjD,WAAW,SAAS,EAAE,EACrB,IAAI,EAAE,kBAAkB,CAAC,aAAa,EAAE,WAAW,CAAC,+DAMrD;AAED,wBAAgB,cAAc,CAC7B,aAAa,SAAS,OAAO,CAAC,kBAAkB,CAAC,EACjD,WAAW,SAAS,EAAE,EAEtB,IAAI,EAAE,kBAAkB,CAAC,aAAa,EAAE,WAAW,CAAC,EACpD,OAAO,CAAC,EAAE,eAAe,8EA0BzB"}
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/integrations/hono.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,kBAAkB,CAAC;AAE5E,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,+DAI5D;AAED,KAAK,eAAe,GAAG;IACtB,OAAO,CAAC,EAAE,oBAAoB,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD,CAAC;AAEF,wBAAgB,QAAQ,CACvB,aAAa,SAAS,OAAO,CAAC,kBAAkB,CAAC,EACjD,WAAW,SAAS,EAAE,EACrB,IAAI,EAAE,kBAAkB,CAAC,aAAa,EAAE,WAAW,CAAC,+DAMrD;AAED,wBAAgB,cAAc,CAC7B,aAAa,SAAS,OAAO,CAAC,kBAAkB,CAAC,EACjD,WAAW,SAAS,EAAE,EAEtB,IAAI,EAAE,kBAAkB,CAAC,aAAa,EAAE,WAAW,CAAC,EACpD,OAAO,CAAC,EAAE,eAAe,8EA0BzB"}

package/dist/plugins/apply-authenticated.d.ts

@@ -0,0 +1,21 @@
+import { type GraphQLSchema } from 'graphql';
+import { type AuthenticatedOptions } from '../directives/authenticated';
+/**
+ * Wraps every object field that an `@authenticated` applies to — on the field,
+ * on its type, on one of its type's interfaces or on that interface's field,
+ * or on the scalar or enum it returns — so the caller is checked before its
+ * resolver (and a subscription's `subscribe`) runs: none is
+ * `UNAUTHENTICATED` (401), one of a type no `type:` names is `FORBIDDEN`
+ * (403). Every one that applies must hold.
+ *
+ * Read and validated when the schema is built: `type: []`, a type outside
+ * `options.types` (`session`, `token` by default) and restrictions with no
+ * type in common each throw a `TypeError` naming `Type.field`.
+ *
+ * The caller is `context.user`, which `useOryAuth` and `useAuth` set; its
+ * type is `context.ory.kind`, or `context.user.tokenType` without Ory. A field
+ * already guarded is left alone, and a schema with none left to guard is
+ * returned as it is, so the plugin's `onSchemaChange` settles.
+ */
+export declare function applyAuthenticated(schema: GraphQLSchema, options?: AuthenticatedOptions): GraphQLSchema;
+//# sourceMappingURL=apply-authenticated.d.ts.map

package/dist/plugins/apply-authenticated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-authenticated.d.ts","sourceRoot":"","sources":["../../src/plugins/apply-authenticated.ts"],"names":[],"mappings":"AAEA,OAAO,EAEN,KAAK,aAAa,EAKlB,MAAM,SAAS,CAAC;AACjB,OAAO,EACN,KAAK,oBAAoB,EAKzB,MAAM,6BAA6B,CAAC;AAUrC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,oBAAyB,GAChC,aAAa,CAaf"}

package/dist/plugins/apply-keto-checks.d.ts

@@ -1,17 +1,20 @@
-import { type GraphQLSchema } from 'graphql';
+import type { GraphQLSchema } from 'graphql';
 import { type ReadOptions } from '../directives';
 /**
- * Wraps every field carrying `@check` or `@permission` so the permission is
- * answered before its resolver runs.
+ * Wraps every field carrying `@permission` so the permission is answered
+ * before its resolver runs.
  *
  * Every requirement is read and validated here, when the schema is built: a
  * malformed path, an argument the field does not declare, an empty group, a
- * namespace outside `options.namespaces` — and a guard on an interface field,
- * which no resolver ever runs through — each throw a `TypeError` naming
- * `Type.field`, so the server does not boot.
+ * namespace outside `options.namespaces`, a guard on an interface field,
+ * which no resolver ever runs through, and a `@check` — removed in 3.0 — each
+ * throw a `TypeError` naming `Type.field`, so the server does not boot.
  *
  * Modelled on `applyGraphqlPolicy` in `@nxgt/security`. Exported on its own
- * because a schema transform is far easier to test than a plugin.
+ * because a schema transform is far easier to test than a plugin. A field it
+ * already guarded is left as it is, and a schema with no field left to guard
+ * is returned as it is — so it never wraps a field twice, and the plugin's
+ * `onSchemaChange` settles.
  */
 export declare function applyKetoChecks(schema: GraphQLSchema, options?: ReadOptions): GraphQLSchema;
 //# sourceMappingURL=apply-keto-checks.d.ts.map

package/dist/plugins/apply-keto-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-keto-checks.d.ts","sourceRoot":"","sources":["../../src/plugins/apply-keto-checks.ts"],"names":[],"mappings":"AAGA,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAIN,KAAK,WAAW,EAIhB,MAAM,eAAe,CAAC;AAOvB;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,WAAgB,GACvB,aAAa,CAkBf"}
+{"version":3,"file":"apply-keto-checks.d.ts","sourceRoot":"","sources":["../../src/plugins/apply-keto-checks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAsB,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAGN,KAAK,WAAW,EAGhB,MAAM,eAAe,CAAC;AAWvB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,WAAgB,GACvB,aAAa,CAmBf"}

package/dist/plugins/auth.d.ts

@@ -1,4 +1,20 @@
 import type { Plugin } from 'graphql-yoga';
 import type { GraphQLBaseContext } from '../types';
-export declare function useAuth(): Plugin<GraphQLBaseContext>;
+import { type GatewayTrustOptions } from './gateway-trust';
+export type UseAuthOptions = GatewayTrustOptions;
+/**
+ * The caller a gateway resolved, read from the GraphQL request's `extensions`
+ * — `user` and `token` — and ONLY for a request `trustedGateway` vouches for.
+ *
+ * `extensions` sits in the request body, which any client writes. A request
+ * without the gateway's proof leaves the context as it was: no `user`, no
+ * `token`, whatever its `extensions` claim. Without a `trustedGateway` this
+ * throws when it is called, so a server cannot boot trusting the body.
+ *
+ *     useAuth({ trustedGateway: gatewaySecret({ secret: env.GATEWAY_SECRET }) })
+ *
+ * An API that resolves its own callers — a Kratos session, a Hydra token —
+ * uses `useOryAuth(ory)` instead.
+ */
+export declare function useAuth(options: UseAuthOptions): Plugin<GraphQLBaseContext>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/plugins/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/plugins/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,wBAAgB,OAAO,IAAI,MAAM,CAAC,kBAAkB,CAAC,CASpD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/plugins/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EACN,KAAK,mBAAmB,EAGxB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAmB3E"}

package/dist/plugins/authenticated.d.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from 'graphql-yoga';
+import type { AuthenticatedOptions } from '../directives/authenticated';
+import type { GraphQLBaseContext } from '../types';
+import type { OryContext } from './ory-auth';
+/**
+ * Enforces `@authenticated` and `@authenticated(type:)` on every schema the
+ * server uses. Goes after the plugin that sets the caller — `useOryAuth(ory)`
+ * or `useAuth({ trustedGateway })`.
+ *
+ * `applyAuthenticated` returns a schema with no field left to guard as it is,
+ * so the replacement settles alongside `useKetoChecks` whatever their order.
+ */
+export declare function useAuthenticated(options?: AuthenticatedOptions): Plugin<GraphQLBaseContext & OryContext>;
+//# sourceMappingURL=authenticated.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated.d.ts","sourceRoot":"","sources":["../../src/plugins/authenticated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,GAAE,oBAAyB,GAChC,MAAM,CAAC,kBAAkB,GAAG,UAAU,CAAC,CAOzC"}

package/dist/plugins/extract-jwt.d.ts

@@ -1,9 +1,22 @@
+import type { ApolloServerPlugin } from '@apollo/server';
 import type { TokenPrincipal } from '@nxgt/shared';
-export declare const extractJwtPlugin: {
-    requestDidStart({ request, contextValue }: import("@apollo/server").GraphQLRequestContext<{
-        jwt?: {
-            payload: TokenPrincipal;
-        };
-    }>): Promise<void>;
+import { type GatewayTrustOptions } from './gateway-trust';
+export type ExtractJwtOptions = GatewayTrustOptions;
+/** What `extractJwtPlugin()` sets on an Apollo context. */
+export type JwtContext = {
+    jwt?: {
+        payload: TokenPrincipal;
+    };
 };
+/**
+ * Apollo Server's counterpart of `useAuth()`: the JWT payload a gateway
+ * verified and forwarded in `request.extensions.payload`, copied onto
+ * `context.jwt` — ONLY for a request `trustedGateway` vouches for.
+ *
+ * A request without the gateway's proof leaves `context.jwt` as the context
+ * function built it, whatever its `extensions` claim.
+ *
+ *     plugins: [extractJwtPlugin({ trustedGateway: gatewaySecret({ secret }) })]
+ */
+export declare function extractJwtPlugin(options: ExtractJwtOptions): ApolloServerPlugin<JwtContext>;
 //# sourceMappingURL=extract-jwt.d.ts.map

package/dist/plugins/extract-jwt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-jwt.d.ts","sourceRoot":"","sources":["../../src/plugins/extract-jwt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,eAAO,MAAM,gBAAgB;;cAWtB;YAAE,OAAO,EAAE,cAAc,CAAA;SAAE;;CAChC,CAAC"}
+{"version":3,"file":"extract-jwt.d.ts","sourceRoot":"","sources":["../../src/plugins/extract-jwt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACN,KAAK,mBAAmB,EAGxB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAEpD,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG;IACxB,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE,CAAC;CAClC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,iBAAiB,GACxB,kBAAkB,CAAC,UAAU,CAAC,CAUhC"}

package/dist/plugins/field-guard.d.ts

@@ -0,0 +1,30 @@
+import { type GraphQLFieldConfig } from 'graphql';
+type FieldConfig = GraphQLFieldConfig<unknown, unknown>;
+/** What a guard asks before a field runs; it throws to refuse. */
+export type FieldCheck = (source: unknown, args: Record<string, unknown>, context: unknown) => void | Promise<void>;
+/**
+ * One transform's guard on one field: its mark, its rank (lower runs first),
+ * its check, and whether the check can run before a subscription's stream is
+ * opened — only when it reads nothing off an event (`parent.<path>`).
+ */
+export type FieldGuard = {
+    mark: string;
+    rank: number;
+    check: FieldCheck;
+    onSubscribe: boolean;
+};
+/**
+ * Whether the transform owning `mark` guards this field as it stands. A
+ * merged schema's unguarded half, or a field whose resolver was replaced,
+ * is not — so a transform run again wraps it, never one twice.
+ */
+export declare function isGuarded(config: FieldConfig, mark: string): boolean;
+/**
+ * The field with `guard` added. Every guard runs by rank — `@authenticated`
+ * before `@permission`, whichever transform ran first — before the resolver;
+ * those with `onSubscribe` also run before `subscribe`, so a refused
+ * subscription opens no stream.
+ */
+export declare function guardField(config: FieldConfig, guard: FieldGuard): FieldConfig;
+export {};
+//# sourceMappingURL=field-guard.d.ts.map

package/dist/plugins/field-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-guard.d.ts","sourceRoot":"","sources":["../../src/plugins/field-guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EAEvB,MAAM,SAAS,CAAC;AAEjB,KAAK,WAAW,GAAG,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAGxD,kEAAkE;AAClE,MAAM,MAAM,UAAU,GAAG,CACxB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,OAAO,KACZ,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACrB,CAAC;AA6BF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,GACf,WAAW,CA6Bb"}

package/dist/plugins/gateway-trust.d.ts

@@ -0,0 +1,47 @@
+import type { TokenPrincipal } from '@nxgt/shared';
+/** One request header — a fetch `Headers`, or Apollo Server's `HeaderMap`. */
+export type HeaderReader = {
+    get(name: string): string | null | undefined;
+};
+/**
+ * Whether a request came from the gateway allowed to name the caller in the
+ * GraphQL request's `extensions`.
+ *
+ * `extensions` is part of the request body, which any client writes. It names
+ * the caller only when this answers `true` — for a request carrying proof the
+ * client cannot forge. `gatewaySecret()` is the usual proof; a function of
+ * your own (an mTLS header set by your proxy, say) works as well.
+ */
+export type GatewayTrust = (headers: HeaderReader) => boolean | Promise<boolean>;
+/** What `useAuth()` and `extractJwtPlugin()` take: who may set the caller. */
+export type GatewayTrustOptions = {
+    trustedGateway: GatewayTrust;
+};
+export type GatewaySecretOptions = {
+    /** Shared with the gateway only. At least 16 characters. */
+    secret: string;
+    /** The header the gateway sends it in. `x-gateway-secret` by default. */
+    header?: string;
+};
+export declare const GATEWAY_SECRET_HEADER = "x-gateway-secret";
+/**
+ * A `GatewayTrust` that holds for a request whose `header` carries `secret`,
+ * compared in constant time. The gateway adds the header to every subgraph
+ * request; a client reaching the service directly does not know it.
+ *
+ * Refuses, when it is built, a secret shorter than 16 characters: an unset
+ * environment variable must stop the server, not trust an empty header.
+ */
+export declare function gatewaySecret({ secret, header, }: GatewaySecretOptions): GatewayTrust;
+/**
+ * The `trustedGateway` a plugin was given, or a `TypeError` naming the plugin:
+ * without one there is no caller it could read, and a plugin that silently
+ * reads none is a server whose every caller is anonymous.
+ */
+export declare function requireGatewayTrust(options: Partial<GatewayTrustOptions> | undefined, plugin: string): GatewayTrust;
+/**
+ * The caller a trusted gateway put in `extensions`, when it is shaped like
+ * one: an object with a non-empty string `sub`. Anything else names nobody.
+ */
+export declare function principalOf(value: unknown): TokenPrincipal | undefined;
+//# sourceMappingURL=gateway-trust.d.ts.map

package/dist/plugins/gateway-trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-trust.d.ts","sourceRoot":"","sources":["../../src/plugins/gateway-trust.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7C,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,OAAO,EAAE,YAAY,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG;IACjC,cAAc,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAClC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAKxD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAC7B,MAAM,EACN,MAA8B,GAC9B,EAAE,oBAAoB,GAAG,YAAY,CAYrC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,SAAS,EACjD,MAAM,EAAE,MAAM,GACZ,YAAY,CAQd;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAMtE"}

package/dist/plugins/index.d.ts

@@ -1,6 +1,9 @@
+export * from './apply-authenticated';
 export * from './apply-keto-checks';
 export * from './auth';
+export * from './authenticated';
 export * from './extract-jwt';
+export * from './gateway-trust';
 export * from './keto-checker';
 export * from './keto-checks';
 export * from './keto-helpers';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,QAAQ,CAAC;AACvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/plugins/keto-checks.d.ts

@@ -14,8 +14,9 @@ export type KetoChecksOptions = ReadOptions;
  * Goes after `useOryAuth(ory)`, which is what puts `ory.subject` there.
  *
  * `replaceSchema` inside `onSchemaChange` re-enters this hook with the new
- * schema, so transformed schemas are remembered and passed through. Without
- * the guard this loops until the stack gives out.
+ * schema, and with every schema another plugin makes of it. `applyKetoChecks`
+ * returns a schema with no field left to guard as it is, so the replacement settles
+ * instead of looping, alongside `useAuthenticated` whatever their order.
  *
  * `OryUnavailable` is deliberately not caught anywhere here: a Keto outage is
  * a 503 through `createMaskError`, never a denial.

package/dist/plugins/keto-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keto-checks.d.ts","sourceRoot":"","sources":["../../src/plugins/keto-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,iBAAsB,GAC7B,MAAM,CAAC,kBAAkB,GAAG,UAAU,GAAG,iBAAiB,CAAC,CAc7D"}
+{"version":3,"file":"keto-checks.d.ts","sourceRoot":"","sources":["../../src/plugins/keto-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,iBAAsB,GAC7B,MAAM,CAAC,kBAAkB,GAAG,UAAU,GAAG,iBAAiB,CAAC,CAU7D"}

package/dist/plugins/keto-helpers.d.ts

@@ -19,7 +19,7 @@ export type CanQuestion = {
     id: string;
 };
 /**
- * The caller, or an `UNAUTHENTICATED` refusal (401 through `createMaskError`).
+ * The caller, or an `UNAUTHENTICATED` refusal: a `GraphQLError` answered 401.
  * An absent caller is not an error to swallow in a resolver that needs one.
  */
 export declare function requireUser(context: {

package/dist/plugins/keto-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keto-helpers.d.ts","sourceRoot":"","sources":["../../src/plugins/keto-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GACjD,UAAU,GACV,iBAAiB,CAAC;AAEnB,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG;IACzB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACpC,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B,GAAG,cAAc,CAOjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,GAAG,CACxB,OAAO,EAAE,UAAU,GAAG,iBAAiB,EACvC,QAAQ,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAkBlB"}
+{"version":3,"file":"keto-helpers.d.ts","sourceRoot":"","sources":["../../src/plugins/keto-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GACjD,UAAU,GACV,iBAAiB,CAAC;AAEnB,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG;IACzB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACpC,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B,GAAG,cAAc,CAKjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,GAAG,CACxB,OAAO,EAAE,UAAU,GAAG,iBAAiB,EACvC,QAAQ,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAgBlB"}

package/dist/plugins/ory-auth.d.ts

@@ -60,9 +60,9 @@ export declare function resolveOryPrincipal(ory: Ory, headers: Headers): Promise
 /**
  * `useAuth()` for an Ory-native API: resolves the caller through Kratos
  * (session cookie, session token) or Hydra (Bearer, introspected) and puts
- * `user`, `claims`, `token` and `ory` on the context. Wire it exactly where the
- * standalone APIs wire `useAuth()`, ahead of `useGenericAuth` — which then
- * enforces `@authenticated` from `context.user` unchanged.
+ * `user`, `claims`, `token` and `ory` on the context. Wire it ahead of
+ * `useAuthenticated()`, which enforces `@authenticated` from `context.user`
+ * and `context.ory.kind`.
  *
  * The `Ory` instance comes from the app's `createOry()` — one per process —
  * and is the same one the services use for `isAllowed`.

package/dist/shared.d.ts

@@ -1,2 +1,2 @@
-export declare const SHARED_TYPE_DEFS = "\ntype Query {\n\t_empty: String\n}\ntype Mutation {\n\t_empty: String\n}\ntype Subscription {\n\t_empty: String\n}\n\ndirective @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM\n\ndirective @policy(policies: [[String!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM\n\ndirective @shareable on OBJECT | FIELD_DEFINITION\n\ndirective @link(url: String!, import: [String!]) on SCHEMA\n\n";
+export declare const SHARED_TYPE_DEFS = "\ntype Query {\n\t_empty: String\n}\ntype Mutation {\n\t_empty: String\n}\ntype Subscription {\n\t_empty: String\n}\n\n\"\"\"\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\ndirective @policy(policies: [[String!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM\n\ndirective @shareable on OBJECT | FIELD_DEFINITION\n\ndirective @link(url: String!, import: [String!]) on SCHEMA\n\n";
 //# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,2aAmB5B,CAAC"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB,ypBAkB5B,CAAC"}

package/dist/utils/errors/denial.d.ts

@@ -0,0 +1,20 @@
+import { ErrorCode } from '@nxgt/shared-exceptions';
+import { GraphQLError } from 'graphql';
+/** The refusals a guard answers, each with its HTTP status. */
+export type DenialCode = ErrorCode.Unauthenticated | ErrorCode.Forbidden | ErrorCode.NotFound;
+/**
+ * A refusal, as the `GraphQLError` a client reads: `extensions.code` and
+ * `extensions.http.status` — `UNAUTHENTICATED` 401, `FORBIDDEN` 403,
+ * `NOT_FOUND` 404 — so any server answers it with its status, with or without
+ * `createMaskError`. What `@permission`, `@authenticated`, `requireUser` and
+ * `can` throw.
+ *
+ * `message` is an i18n key (the shared `errors.*` one by default). It is
+ * translated here with `@nxgt/i18n`'s resources, in the request's language
+ * when one is known; `createMaskError(translate)` and
+ * `createFormatError(translate)` translate it again with yours.
+ */
+export declare function denial(code: DenialCode, message?: string): GraphQLError;
+/** The i18n key of a `denial()`, or `undefined` for any other error. */
+export declare function denialMessageKey(error: unknown): string | undefined;
+//# sourceMappingURL=denial.d.ts.map

package/dist/utils/errors/denial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"denial.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/denial.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GACnB,SAAS,CAAC,eAAe,GACzB,SAAS,CAAC,SAAS,GACnB,SAAS,CAAC,QAAQ,CAAC;AAsBtB;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAOvE;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAInE"}

package/dist/utils/errors/format-error.d.ts

@@ -5,7 +5,8 @@ import type { GraphQLBaseContext } from '../../types';
  * Apollo Server's `formatError`, taught this repo's exceptions — the Apollo
  * counterpart of `createMaskError`. `OryUnavailable` answers
  * `SERVICE_UNAVAILABLE`, never a denial and never an opaque
- * `INTERNAL_SERVER_ERROR`.
+ * `INTERNAL_SERVER_ERROR`; a `denial()` keeps its code, and its message is
+ * translated with `translate`.
  */
 export declare function createFormatError<K extends LocaleKey, C extends GraphQLBaseContext = GraphQLBaseContext>(translate?: (message: K, context?: TranslationContext) => string, production?: boolean): ApolloServerOptions<C>['formatError'];
 //# sourceMappingURL=format-error.d.ts.map

package/dist/utils/errors/format-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/format-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAK1D,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,EAEjD,SAAS,GAAE,CACV,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAsB,EAC3B,UAAU,CAAC,EAAE,OAAO,GAClB,mBAAmB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CA4DvC"}
+{"version":3,"file":"format-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/format-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAK1D,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAChC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,EAEjD,SAAS,GAAE,CACV,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAsB,EAC3B,UAAU,CAAC,EAAE,OAAO,GAClB,mBAAmB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAgEvC"}

package/dist/utils/errors/index.d.ts

@@ -1,4 +1,5 @@
 export * from './create-error';
+export * from './denial';
 export * from './format-error';
 export * from './mask-error';
 export * from './ory-unavailable';

package/dist/utils/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC"}

package/dist/utils/errors/mask-error.d.ts

@@ -12,7 +12,8 @@ type Translate<K extends LocaleKey> = (message: K, context?: TranslationContext)
  * (`UNAUTHENTICATED` 401, `FORBIDDEN` 403, `NOT_FOUND` 404); a Mongoose error
  * goes through `castError` first, as `createFormatError` does for Apollo.
  * `OryUnavailable` (@nxgt/ory-sdk) becomes a 503 `SERVICE_UNAVAILABLE`, never
- * a denial. Everything else is masked as Yoga's default masks it: a
+ * a denial. A `denial()` — what the directives, `requireUser` and `can` throw
+ * — keeps its code and status, and its message is translated with `translate`. Everything else is masked as Yoga's default masks it: a
  * `GraphQLError` thrown on purpose — or raised by validation — passes, and one
  * that only wraps a plain `Error` a resolver threw is replaced by `message`,
  * so an internal message never reaches the client.

package/dist/utils/errors/mask-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mask-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/mask-error.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,KAAK,SAAS,CAAC,CAAC,SAAS,SAAS,IAAI,CACrC,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAM,CAAC;AAEZ;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EAClD,SAAS,GAAE,SAAS,CAAC,CAAC,CAAiB,GACrC,SAAS,CA2BX"}
+{"version":3,"file":"mask-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/mask-error.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,KAAK,SAAS,CAAC,CAAC,SAAS,SAAS,IAAI,CACrC,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAM,CAAC;AAEZ;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EAClD,SAAS,GAAE,SAAS,CAAC,CAAC,CAAiB,GACrC,SAAS,CAmCX"}

package/dist/utils/ws-context.d.ts

@@ -8,7 +8,7 @@ export interface ResolvedWsUser {
 }
 /**
  * Resolves the authenticated TokenPrincipal for a `graphql-ws` connection - the
- * WS-transport equivalent of the HTTP-path `useAuth()`/`useGenericAuth()`
+ * WS-transport equivalent of the HTTP-path `useOryAuth()` / `useAuth()`
  * plugins. There is no gateway hop for WS connections, so each app performs
  * the OAuth introspection call itself using its own `auth` client.
  *

package/docs/README.md

@@ -3,9 +3,11 @@
 The package's [README](../README.md) is the short version, with one example
 per section. These pages are the long one.
 
-- [Guide: permissions](./guide/permissions.md) — `@permission`, `@check`,
-  `useKetoChecks`, build-time validation, `requireUser` and `can`
-- [Guide: errors](./guide/errors.md) — `createMaskError`, `createFormatError`,
-  the codes and statuses, and why an outage is a 503
-- [Troubleshooting](./troubleshooting.md) — each error by the message you see
-- [Roadmap](./roadmap.md) — what is next, including the planned major
+| Page | Read it when |
+| --- | --- |
+| [Migrating to 3.0](./guide/migrating-to-3.md) | you upgrade from 2.x: every break, with the code before and after |
+| [Authentication](./guide/authentication.md) | you wire `useOryAuth`, `useAuth` behind a trusted gateway, or `@authenticated(type:)` |
+| [Permissions](./guide/permissions.md) | you guard a field with `@permission`, or call `requireUser` / `can` |
+| [Errors](./guide/errors.md) | you decide what a client receives: denials, `createMaskError`, `createFormatError`, outages |
+| [Troubleshooting](./troubleshooting.md) | you have an error message in hand |
+| [Roadmap](./roadmap.md) | you want to know what is next, and what shipped in 3.0 |

package/docs/guide/authentication.md

@@ -0,0 +1,187 @@
+# Authentication: who is calling, and `@authenticated`
+
+A resolver reads the caller from `context.user`. This page is where that value
+comes from, which sources are trusted, and how `@authenticated` refuses a
+missing caller or one of the wrong kind.
+
+## The rule: a verified source, never the body alone
+
+The GraphQL request's `extensions` travel in the request body, which any
+client writes. So the caller comes from one of two places:
+
+| Source | Plugin | Verified by |
+| --- | --- | --- |
+| a Kratos session or a Hydra access token | `useOryAuth(ory)` | Ory, server-side, on every request |
+| what a gateway resolved and put in `extensions` | `useAuth()` / `extractJwtPlugin()` | the gateway's proof — `trustedGateway` — on every request |
+
+Anything else leaves the context without a caller.
+
+## `useOryAuth(ory)` — an API that authenticates its own callers
+
+```ts
+import { createOry } from '@nxgt/ory-sdk';
+import { useAuthenticated, useOryAuth } from '@nxgt/shared-graphql';
+
+const ory = createOry({ /* … */ });
+
+createYoga({ plugins: [useOryAuth(ory), useAuthenticated()] });
+```
+
+It reads `Authorization: Bearer`, then `X-Session-Token`, then the Kratos
+cookie, and puts `user`, `claims`, `token` and `ory` on the context. An Ory
+outage throws a 503 `SERVICE_UNAVAILABLE`, never an anonymous caller.
+
+## `useAuth()` and `extractJwtPlugin()` — behind a gateway
+
+A gateway that authenticated the caller can forward it to subgraphs in the
+request's `extensions`: `user` and `token` for `useAuth()` (Yoga),
+`payload` for `extractJwtPlugin()` (Apollo Server). Both read it **only** when
+`trustedGateway` holds for the request:
+
+```ts
+import { extractJwtPlugin, gatewaySecret, useAuth } from '@nxgt/shared-graphql';
+
+const trustedGateway = gatewaySecret({ secret: process.env.GATEWAY_SECRET! });
+
+createYoga({ plugins: [useAuth({ trustedGateway })] });
+new ApolloServer({ plugins: [extractJwtPlugin({ trustedGateway })] });
+```
+
+### `gatewaySecret({ secret, header? })`
+
+Holds for a request whose `header` — `x-gateway-secret` by default — carries
+`secret`, compared in constant time. The gateway adds it to every subgraph
+request; a client that reaches the service directly does not know it, and its
+`extensions` are ignored.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `secret` | — | shared with the gateway only; **at least 16 characters**, or `gatewaySecret` throws when it is built |
+| `header` | `x-gateway-secret` | the header the gateway sends it in |
+
+The length check is there for the day `GATEWAY_SECRET` is unset: the server
+stops at boot instead of trusting an empty header.
+
+### Another proof
+
+`trustedGateway` is any function of the request's headers:
+
+```ts
+type GatewayTrust = (headers: { get(name: string): string | null | undefined }) => boolean | Promise<boolean>;
+
+// Your proxy terminates mTLS and sets this header only for the gateway's certificate.
+useAuth({ trustedGateway: (headers) => headers.get('x-client-cert-subject') === 'CN=gateway' });
+```
+
+It receives a fetch `Headers` under Yoga and Apollo's `HeaderMap` under
+Apollo Server; both answer `get`.
+
+### What is read
+
+- `useAuth()`: `extensions.user` when it is an object with a non-empty string
+  `sub`, and `extensions.token` when it is a string. Otherwise nothing.
+- `extractJwtPlugin()`: `extensions.payload`, under the same `sub` rule, on
+  `context.jwt.payload`.
+- A request that fails the proof leaves `user`, `token` and `jwt` as they
+  were — another plugin's caller is not erased.
+- Over WebSocket, `useAuth()` reads no caller: the proof needs a fetch
+  `Request`, which a graphql-ws context does not hold. Resolve the caller per
+  connection with `resolveWsUser` instead.
+
+Without a `trustedGateway`, both throw a `TypeError` when called — see
+[troubleshooting](../troubleshooting.md).
+
+## `@authenticated(type: [String!])`
+
+```graphql
+directive @authenticated(type: [String!]) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
+```
+
+Declared in `SHARED_TYPE_DEFS` and in `AUTHENTICATED_DIRECTIVE_SDL`; enforced
+by `useAuthenticated()`, or `applyAuthenticated(schema)` on a built schema.
+
+```graphql
+type Query {
+	me: User @authenticated                      # any caller
+	webhooks: [Webhook!]! @authenticated(type: ["token"])  # a machine client, not a session
+}
+
+interface Node @authenticated { id: ID! }
+type Staff implements Node @authenticated(type: ["session"]) { id: ID!, name: String }
+```
+
+| Caller | Answer |
+| --- | --- |
+| none (`context.user` unset) | `UNAUTHENTICATED`, HTTP 401 |
+| of a type no applicable `type:` names | `FORBIDDEN`, HTTP 403 |
+| otherwise | the resolver runs |
+
+- **The caller's type** is `context.ory.kind` — `session` for a Kratos
+  session, `token` for an access token — or `context.user.tokenType` when no
+  Ory principal is on the context.
+- **Every directive that applies is AND-ed**: the field's, its type's, its
+  type's interfaces', and those interfaces' same field. `Staff.name` above
+  needs a caller (`Node`) who is a session (`Staff`).
+- **A scalar's or an enum's directive guards every field returning it** —
+  `scalar Secret @authenticated` refuses `Query.secret: Secret` to an
+  anonymous caller, as federation's router reads it.
+- **A subscription is refused before its stream opens**: the check runs
+  before the field's `subscribe`, and again before each event is resolved.
+- **A type's directive guards its fields, not the field returning it.**
+  `Query.staff` runs for an anonymous caller; the error lands on
+  `staff.name`. Put `@authenticated` on the field too when the lookup must not
+  run.
+
+### Other caller types
+
+```ts
+import { CALLER_TYPES, useAuthenticated } from '@nxgt/shared-graphql';
+
+useAuthenticated({ types: [...CALLER_TYPES, 'service'] });
+```
+
+`types` lists every value a `type:` may name; `CALLER_TYPES` —
+`['session', 'token']` — is the default. Behind a gateway, it is the set
+of `tokenType`s your gateway writes.
+
+### Refused at build
+
+`applyAuthenticated` throws a `TypeError` for a directive no request could
+pass, naming where it sits — `Query.me` on a field, `Staff` on a type,
+`Secret` on a scalar:
+
+| Mistake | Message starts |
+| --- | --- |
+| `type: []` | ``@authenticated on Query.me: `type: []` admits no caller`` |
+| a type outside `types` | `@authenticated on Query.me: unknown type "staff" — known: session, token` |
+| restrictions with no type in common | ``@authenticated on Note.body: the field's, its type's and its interfaces' `type`s have none in common`` |
+
+### Federation's `@authenticated`
+
+Federation defines its own `@authenticated`, with **no argument**, and a
+subgraph imports it:
+
+```graphql
+extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@authenticated"])
+```
+
+`useAuthenticated` accepts that shape: an `@authenticated` whose declaration
+has no `type` means "any caller", and is enforced as such. So in a subgraph,
+keep federation's declaration — `FEDERATION_DIRECTIVES` carries it unchanged
+— and do not load `SHARED_TYPE_DEFS` beside it. `type:` is for a schema that
+declares `@authenticated` through `SHARED_TYPE_DEFS` or
+`AUTHENTICATED_DIRECTIVE_SDL`.
+
+### Beside `useKetoChecks`
+
+Both plugins replace the schema. Each marks the fields it guarded and leaves a
+marked field alone, so the two settle on one schema in either order — and a
+schema merged from a guarded half and an unguarded one gets the second half
+guarded when it is transformed again, as is a field whose resolver was
+replaced since. On a field carrying both,
+`@authenticated` is checked before `@permission` whatever the plugin order,
+so a caller of the wrong type is `FORBIDDEN` before Keto is asked:
+
+```ts
+plugins: [useOryAuth(ory), useAuthenticated(), useKetoChecks(ory)]
+```