@nxgt/janus-graphql 0.2.0 → 0.4.0

package/README.md

@@ -3,9 +3,9 @@
 [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus) in a GraphQL
 server: the signed-in user on the context, authenticated only when a field
 asks, fields and types guarded by `@authenticated`, `@fresh` and
-`@permission`, and
-every error answered with the status it deserves — an outage as 503, never
-as 401, 403 or 404.
+`@permission`, the
+same guards on subscriptions over graphql-ws, and every error answered with
+the status it deserves — an outage as 503, never as 401, 403 or 404.
 
 An [envelop](https://the-guild.dev/graphql/envelop) plugin, so it runs in
 [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) and any server built
@@ -52,7 +52,7 @@ bun add @nxgt/janus-graphql @nxgt/janus graphql @graphql-tools/utils @envelop/co
 bun add -d typescript        # 6
 ```
 
-Every peer is required:
+Every peer is required but `graphql-ws`:
 
 | Peer | Range | Why |
 | --- | --- | --- |
@@ -61,11 +61,12 @@ Every peer is required:
 | `@graphql-tools/utils` | `>=10.0.0 <13` | `mapSchema` and `getDirective`, which apply the directives |
 | `@envelop/core` | `^5.0.0` | Types only — the `Plugin` `useJanus()` answers. Yoga already brings it |
 | `typescript` | `^6.0.3` | As for `@nxgt/janus` |
+| `graphql-ws` | `^6.0.0`, **optional** | Only for subscriptions over a WebSocket, with `janusConnection()`. Nothing here imports it. For `graphql` 17, a `graphql-ws` whose peer range includes it — 6.3.0 does |
 
 The floors are tested, not claimed: the package's specs and its typecheck run
-on `graphql` 16.9.0, `@graphql-tools/utils` 10.0.0 and `@envelop/core` 5.0.0
-as well, together, with a single copy of `graphql`, in the Floors job, on
-every CI run.
+on `graphql` 16.9.0, `@graphql-tools/utils` 10.0.0, `@envelop/core` 5.0.0
+and `graphql-ws` 6.0.0 as well, together, with a single copy of `graphql`,
+in the Floors job, on every CI run.
 
 Like `@nxgt/janus`, it expects `"moduleResolution": "bundler"`: the
 declarations import without extensions, so `nodenext` is not supported.
@@ -78,7 +79,7 @@ that reads files — `node_modules/@nxgt/janus-graphql/graphql/janus.graphqls`.
 
 | Export | What it is |
 | --- | --- |
-| `useJanus({ auth, access?, type?, clock?, loaders?, conditions? })` | The envelop plugin. Adds `ctx.janus` to every request's context, and applies the directives to every schema the server is given, once. `type` treats a user of any other type as anonymous. `clock` is what `@fresh` and `requireFresh()` read — the one given to `janus()`, when it is not the system's. `loaders` and `conditions` are what `@permission` needs beside `access` |
+| `useJanus({ auth, access?, type?, clock?, loaders?, conditions? })` | The envelop plugin. Adds `ctx.janus` to every request's context, and applies the directives to every schema the server is given, once. `type` treats a user of any other type as anonymous. `clock` is what `@fresh` and `requireFresh()` read — the one given to `janus()`, when it is not the system's. `loaders` and `conditions` are what `@permission` needs beside `access`. Under Yoga, a session `authenticate` renewed is sent again as `Set-Cookie` on the response, to a request that presented it as the cookie |
 | `ctx.janus.user()`, `ctx.janus.session()` | Who the request belongs to, and the session it presented — `null` for an anonymous request. `auth.authenticate(request)` runs the first time either is asked, once per request, and never when neither is |
 | `ctx.janus.access` | The `permissions()` instance given to `useJanus()`. Absent from the type — and from the context — without one |
 | `janusTypeDefs` | The SDL: `@authenticated`, `@fresh`, `@permission` and the `JanusPermissionDenial` enum — prefixed, so it never collides with a type of your schema. The same text as `graphql/janus.graphqls` |
@@ -91,11 +92,12 @@ that reads files — `node_modules/@nxgt/janus-graphql/graphql/janus.graphqls`.
 | `requireUser(ctx, { type? })` | The signed-in user, narrowed to `type` — one or a non-empty list — or a denial: `UNAUTHENTICATED`, `FORBIDDEN` |
 | `requireFresh(ctx, maxAge)` | The request's session, once it proved who it is less than `maxAge` ago — a duration with its unit, `'10m'`, never a bare number — or a denial: `UNAUTHENTICATED`, `STEP_UP_REQUIRED` |
 | `can(ctx, permission, object, options?)` | `access.can` for the request's user, typed as `access.can` is. Anonymous answers `false`. Shares the request's checks with `@permission`: one question, one check per request |
-| `janusMaskError(fallback?)` | Yoga's `maskedErrors.maskError`: a `JanusError` a resolver let through answered with its code and status; anything else to `fallback` |
+| `janusConnection({ auth, access?, type?, clock?, upgrade? })` | Subscriptions over graphql-ws: `onConnect` for its `useServer()`, which accepts a connection whose `connectionParams.authorization` — else whose upgrade request's headers or cookie — authenticates, as a user of `type` when given, and refuses any other `4403`; an outage rejects, closed `4500`. Each operation's `ctx.janus` then authenticates from that credential, so the directives hold unchanged. `context` builds `{ janus }` for a server without Yoga; `upgrade` reads the upgrade request where the transport's `extra` does not carry it — Bun |
+| `janusMaskError({ report?, fallback? })` | Yoga's `maskedErrors.maskError`: a `JanusError` a resolver let through answered with its code and status; anything else to `fallback`. `report` is called once with every `JanusError` answered 5xx — a directive's and a helper's too — and cannot change the answer. `janusMaskError(fallback)`, the fallback alone, still works |
 | `janusGraphQLError(error)` | A `JanusError` as the `GraphQLError` the client reads: its code, its status, and only what the client can act on |
 | `denial(code, message?)` | A denial of your own: `UNAUTHENTICATED` 401, `FORBIDDEN` 403, `NOT_FOUND` 404. For a stale session, call `requireFresh()`, whose `STEP_UP_REQUIRED` is `@nxgt/janus`'s |
 | `JanusContext<typeof auth, typeof access?, Type?>` | What `useJanus()` adds to the context, for your resolvers' `ctx` |
-| `JanusOptions`, `JanusOnContext`, `JanusDirectivesOptions`, `Loaders`, `Conditions`, `LoadedObject`, `RequireUserOptions`, `Auth`, `UserOfAuth`, `DenialCode`, `MaskError` | The types of the arguments and answers above |
+| `JanusOptions`, `JanusOnContext`, `JanusConnectionOptions`, `JanusConnection`, `ConnectionContext`, `JanusDirectivesOptions`, `Loaders`, `Conditions`, `LoadedObject`, `RequireUserOptions`, `Auth`, `UserOfAuth`, `DenialCode`, `MaskError`, `JanusMaskErrorOptions` | The types of the arguments and answers above |
 
 ## Directives
 
@@ -145,6 +147,46 @@ model does not declare, a malformed `id:`, an argument the field does not
 take, a missing loader or condition, a `maxAge` not above zero — is a
 `TypeError` at start-up naming the field. Detail: [the directives guide](docs/guide/directives.md).
 
+## Subscriptions over graphql-ws
+
+Yoga's recommended graphql-ws setup, with `onConnect` added:
+
+```ts
+import { janusConnection } from '@nxgt/janus-graphql';
+import { useServer } from 'graphql-ws/use/ws';
+
+useServer(
+	{
+		onConnect: janusConnection({ auth }).onConnect, // no valid session: closed 4403
+		execute: (args: any) => args.rootValue.execute(args),
+		subscribe: (args: any) => args.rootValue.subscribe(args),
+		onSubscribe: async (ctx, _id, params) => {
+			const { schema, execute, subscribe, contextFactory, parse, validate } =
+				yoga.getEnveloped({ ...ctx, req: ctx.extra.request, socket: ctx.extra.socket, params });
+			const args = {
+				schema,
+				operationName: params.operationName,
+				document: parse(params.query),
+				variableValues: params.variables,
+				contextValue: await contextFactory(), // useJanus() finds the connection by ctx.extra
+				rootValue: { execute, subscribe },
+			};
+			const errors = validate(args.schema, args.document);
+			return errors.length ? errors : args;
+		},
+	},
+	wsServer,
+);
+```
+
+A browser's session cookie travels on the upgrade request; any other client
+sends `connectionParams: { authorization: 'Bearer <token>' }`, which is
+read first. Each operation is authenticated again from that credential
+when it subscribes: `@authenticated` and `@fresh` are checked then, and
+`@permission` on every event. A session revoked mid-stream is refused at
+the next subscribe, not at the next event. Detail, Bun, and a server
+without Yoga: [the subscriptions guide](docs/guide/subscriptions.md).
+
 ## Errors
 
 This package defines **no error class**. A denial is a `GraphQLError`, and
@@ -170,6 +212,25 @@ else — never `reason`, `login`, a hash prefix or a cause. The message is a
 fixed one per status, never the core's: read `code`. Detail, and the status of a
 response with several errors: [the errors guide](docs/guide/errors.md).
 
+The message carries nothing of the store's, and a directive answers an
+outage itself, before any resolver of yours could log it. `report` sees
+every `JanusError` answered 5xx, once, whichever path it took:
+
+```ts
+import { maskError } from 'graphql-yoga';
+
+createYoga({
+	schema,
+	plugins: [useJanus({ auth, access })],
+	maskedErrors: {
+		maskError: janusMaskError({
+			report: (error) => logger.error({ code: error.code, cause: error.cause }), // slot, operation: which call failed
+			fallback: maskError, // Yoga's own, for everything else
+		}),
+	},
+});
+```
+
 ## Traps
 
 - **Without `janusMaskError()`, a `JanusError` from a resolver is Yoga's
@@ -187,10 +248,16 @@ response with several errors: [the errors guide](docs/guide/errors.md).
   the highest `extensions.http.status` among the errors, so `{ open me }`
   from an anonymous request is a 401 whose `data` still holds `open`. A client
   reads `data` and `errors`, not only the status.
-- **A renewed session is not sent back as a cookie.** `authenticate` renews
-  a sliding session in passing, and nothing here sets `Set-Cookie` on the
-  GraphQL response: a browser keeps the cookie with its old expiry. Sign in
-  and renew through your HTTP routes, or send a bearer token.
+- **A renewed session is sent back only on an HTTP response from Yoga.**
+  `useJanus()` sets it in Yoga's `onResponse`, which a server on envelop
+  alone never calls; and an operation over graphql-ws has no response at
+  all. There, `ctx.janus` still renews the session in the store, but the
+  browser keeps the cookie with its old expiry until the next renewal over
+  HTTP, a `renewAfter` later: a browser whose only traffic is the WebSocket
+  should renew through an HTTP route of yours.
+- **An `auth` of your own needs `cookie` for the renewal.** A wrapper that
+  passes on only `authenticate` and `types` sends no renewed cookie; pass
+  `cookie: auth.cookie` along.
 - **`useJanus({ type })` narrows the whole server.** A user of any other type
   is anonymous everywhere, and a directive naming another type is refused
   when the schema is built.
@@ -218,8 +285,19 @@ response with several errors: [the errors guide](docs/guide/errors.md).
   on every one, and one denial denies the field; to answer only the items a
   user may see, ask `access.list()` for their ids.
 - **A context built without a request cannot authenticate.** `ctx.janus.user()`
-  rejects with a `TypeError` — a transport that is not HTTP, such as a
-  WebSocket, needs its own wiring, which is on the [roadmap](docs/roadmap.md).
+  rejects with a `TypeError` — a transport that is not HTTP, or a graphql-ws
+  operation whose connection no `janusConnection().onConnect` accepted, or
+  whose context was built without Yoga's `...ctx` spread, which carries
+  `ctx.extra`.
+- **A session revoked while a socket is open keeps its running streams.**
+  An operation authenticates once, when it subscribes, and each event's
+  `@authenticated` reads that answer; the next subscribe, and a
+  reconnection, are refused. Close the
+  socket yourself to cut it at once. `@permission` sees a `revoke()` at the
+  next event.
+- **Bun's graphql-ws `extra` holds no request.** Without
+  `janusConnection({ upgrade })`, a browser's cookie is never read there,
+  and only `connectionParams` authenticates.
 - **`@fresh` reads seconds; `requireFresh()` a duration.** `@fresh(maxAge:
   10)` is ten seconds, not ten minutes — write `600`. `requireFresh(ctx,
   '10m')` takes the unit, and refuses a bare number, which `@nxgt/janus`
@@ -238,13 +316,13 @@ response with several errors: [the errors guide](docs/guide/errors.md).
 
 ## Documentation
 
-- [Guides](docs/README.md) — the directives, the step-up over GraphQL, the context and the lazy user, errors as statuses, telemetry, and federation
+- [Guides](docs/README.md) — the directives, the step-up over GraphQL, subscriptions over graphql-ws, the context and the lazy user, errors as statuses, telemetry, and federation
 - [Troubleshooting](docs/troubleshooting.md) — by the message or status you see
 - [Roadmap](docs/roadmap.md) — what is next, and what is not planned
 
 ## Type safety, counted
 
-Twenty-nine plausible mistakes are refused by the compiler, each with a
+Thirty-seven plausible mistakes are refused by the compiler, each with a
 `@ts-expect-error` case in `test/types/`:
 
 - five in `context.ts`: reading the user or the session where either may be
@@ -257,10 +335,11 @@ Twenty-nine plausible mistakes are refused by the compiler, each with a
   permission the object's type does not declare, an object type the model
   does not, an object without a field a `fromField` reads, a condition reached
   with no `ctx`, a `ctx` of the wrong shape, and a context with no `access`;
-- five in `plugin.ts`: `useJanus()` given a user type the instance does not
+- seven in `plugin.ts`: `useJanus()` given a user type the instance does not
   know, something that is not what `janus()` answered, the `permissions()`
-  instance as `auth`, and `applyJanusDirectives()` without `auth` or narrowed
-  to a user type the instance does not know;
+  instance as `auth`, `applyJanusDirectives()` without `auth` or narrowed
+  to a user type the instance does not know, and `janusMaskError()` given a
+  misspelled `report` or one reading what a `JanusError` does not carry;
 - five in `wiring.ts`: `useJanus()`'s `loaders` for an object type the model
   does not declare, a loader answering an object without a field a
   `fromField` reads, `conditions` for a type no `when()` is reached on, a
@@ -268,9 +347,16 @@ Twenty-nine plausible mistakes are refused by the compiler, each with a
   `access`;
 - five in `fresh.ts`: `requireFresh()` given a bare number, a duration
   written as prose, no `maxAge` at all, or the request instead of the
-  context, and `useJanus()` given a timestamp as its `clock`.
-
-`plugin.ts` also holds this README's quick start, which must keep compiling.
+  context, and `useJanus()` given a timestamp as its `clock`;
+- six in `connection.ts`: `janusConnection()` given a user type the
+  instance does not know, the `permissions()` instance as `auth`, or a
+  timestamp as its `clock`; `ctx.janus.access` from a connection given no
+  `access`, a field of another user type once narrowed, and an `upgrade`
+  answering a token rather than a request.
+
+`plugin.ts` also holds this README's quick start, and `connection.ts` the
+graphql-ws wiring — Yoga's recipe, without Yoga, and Bun's `upgrade` —
+against graphql-ws's own types; both must keep compiling.
 
 ## Licence
 

package/dist/connection/connection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `janusConnection()`: authenticated subscriptions over graphql-ws.
+ */
+import type { Auth, UserOfAuth } from '../types';
+import type { JanusConnection, JanusConnectionOptions } from './types';
+/**
+ * The pieces of graphql-ws's `useServer()` that authenticate a WebSocket
+ * connection, for Yoga's recommended setup:
+ *
+ * ```ts
+ * const connection = janusConnection({ auth });
+ * useServer({
+ *   onConnect: connection.onConnect,
+ *   execute: (args) => args.rootValue.execute(args),
+ *   subscribe: (args) => args.rootValue.subscribe(args),
+ *   onSubscribe: async (ctx, _id, params) => { … yoga.getEnveloped({ ...ctx, … }) … },
+ * }, wsServer);
+ * ```
+ *
+ * `onConnect` reads the connection's credential — `connectionParams`'
+ * `authorization`, else the upgrade request's headers and cookie — and
+ * refuses it unless it authenticates, as a user of `type` when it is given.
+ * Each operation on the connection then gets a `ctx.janus` of its own from
+ * `useJanus()`, authenticated again from that credential when a field asks:
+ * `@authenticated`, `@fresh` and `@permission` hold as over HTTP, and a
+ * session revoked since the connection opened is refused at the next
+ * subscribe.
+ *
+ * A server without Yoga passes `context` too, and applies the directives
+ * with `applyJanusDirectives()`.
+ */
+export declare function janusConnection<A extends Auth<{
+    readonly type: string;
+    readonly id: string;
+}>, P extends object | undefined = undefined, const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: JanusConnectionOptions<A, P, T>): JanusConnection<A, P, T>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/connection/connection.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAgB,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAC9B,CAAC,SAAS,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9D,CAAC,SAAS,MAAM,GAAG,SAAS,GAAG,SAAS,EACxC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAC5D,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAqCpE"}

package/dist/connection/credential.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The credential a graphql-ws connection presents, and the connections
+ * `janusConnection().onConnect` accepted: what each operation on one is
+ * authenticated from.
+ */
+import type { RequestLike } from '@nxgt/janus';
+import type { ConnectionContext } from './types';
+/** Where the upgrade request is, when the transport does not say `extra.request`. */
+export type Upgrade = (ctx: ConnectionContext) => RequestLike | undefined;
+/**
+ * The connection's credential, as `auth.authenticate` reads one:
+ *
+ * 1. `connectionParams.authorization`, when it is a `Bearer` token — a
+ *    non-browser client's `'Bearer <token>'`;
+ * 2. otherwise the upgrade request itself, read as any request is —
+ *    `Authorization`, then `X-Session-Token`, then the session cookie a
+ *    browser sends with it.
+ *
+ * **The first present wins, not the first valid one**, as in `@nxgt/janus`:
+ * a lapsed token in `connectionParams` beside a live cookie is refused. An
+ * `authorization` of another scheme (`Basic`) is not a session credential,
+ * as in `@nxgt/janus`, and does not count. `null` when there is nothing to
+ * read, or an `authorization` that is not a string — refused, as a
+ * client's mistake.
+ */
+export declare function credentialOf(ctx: ConnectionContext, upgrade: Upgrade | undefined): RequestLike | null;
+/** Remembers `credential` as the one `ctx`'s connection presented. */
+export declare function accept(ctx: ConnectionContext, credential: RequestLike): void;
+/**
+ * The credential of the connection a context was built for, or `undefined`
+ * for one no `onConnect` accepted — and for every HTTP request.
+ */
+export declare function acceptedOf(context: unknown): RequestLike | undefined;
+//# sourceMappingURL=credential.d.ts.map

package/dist/connection/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../../src/connection/credential.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,WAAW,GAAG,SAAS,CAAC;AAK1E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC1B,WAAW,GAAG,IAAI,CAcpB;AAWD,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,GAAG,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,QAQrE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAIpE"}

package/dist/connection/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The public types of `janusConnection()`: what it takes, and the pieces
+ * it answers for graphql-ws's `useServer()`. Typed by their shape, so the
+ * package imports nothing from graphql-ws. Nothing here runs.
+ */
+import type { Clock, RequestLike } from '@nxgt/janus';
+import type { JanusContext, UserOfAuth } from '../types';
+/**
+ * The part of graphql-ws's `Context` read here: the `connectionParams` the
+ * client sent with `connection_init`, and the transport's `extra` —
+ * `{ socket, request }` for `graphql-ws/use/ws`.
+ */
+export interface ConnectionContext {
+    readonly connectionParams?: Readonly<Record<string, unknown>> | undefined;
+    readonly extra: unknown;
+}
+/** What `janusConnection()` takes. */
+export interface JanusConnectionOptions<A, P, T extends string> {
+    /** What `janus()` answered. */
+    readonly auth: A;
+    /**
+     * What `permissions()` answered: `ctx.janus.access` in the context
+     * `context()` builds. `useJanus()`'s own when Yoga builds it.
+     */
+    readonly access?: P;
+    /** Only a user of this type may connect; any other is refused. */
+    readonly type?: T;
+    /** The clock `@fresh` reads in the context `context()` builds. */
+    readonly clock?: Clock;
+    /**
+     * The upgrade request of a connection, for a transport whose `extra`
+     * does not carry it as `request` — Bun's is `{ socket }`:
+     * `upgrade: (ctx) => ctx.extra.socket.data.request`, with the request
+     * passed to `server.upgrade(req, { data: { request: req } })`.
+     *
+     * A method, so `ctx` may be annotated with the transport's own `extra`.
+     */
+    upgrade?(ctx: ConnectionContext): RequestLike | undefined;
+}
+/** What `janusConnection()` answers: the pieces of graphql-ws's `useServer()`. */
+export interface JanusConnection<A, P = undefined, T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']> {
+    /**
+     * `useServer({ onConnect })`: accepts a connection whose credential
+     * authenticates, and answers `false` for any other — graphql-ws closes
+     * it `4403: Forbidden`. An outage rejects, never `false`: the transport
+     * closes it `4500`, and the client does not retry it as a refusal.
+     */
+    readonly onConnect: (ctx: ConnectionContext) => Promise<boolean>;
+    /**
+     * `useServer({ context })`, for a server without Yoga: `ctx.janus` for
+     * one operation, authenticated from the connection's credential. Yoga's
+     * recipe builds the context itself, and `useJanus()` finds the
+     * connection there: leave this out.
+     */
+    readonly context: (ctx: ConnectionContext) => JanusContext<A, P, T>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/connection/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM;IAC7D,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAG,WAAW,GAAG,SAAS,CAAC;CAC1D;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe,CAC/B,CAAC,EACD,CAAC,GAAG,SAAS,EACb,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvD;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACpE"}

package/dist/context.d.ts

@@ -34,17 +34,26 @@ export interface ContextOptions {
     } | undefined;
     readonly type?: string | undefined;
     readonly clock?: Clock | undefined;
+    /** The call the consumer wrote, named by the no-request `TypeError`. */
+    readonly caller?: string;
 }
 /**
  * `ctx.janus` for one request. `authenticate` runs the first time `user()`
  * or `session()` is asked, once, and its answer — or its failure — is the
  * answer of both from then on.
  *
- * A context with no request — a transport that is not HTTP — answers a
+ * A context with no request — a transport that is not HTTP, or a graphql-ws
+ * connection no `janusConnection().onConnect` accepted — answers a
  * `TypeError` from `user()`, not `null`: anonymous is an answer, and nothing
  * here asked.
  */
 export declare function createJanusContext(request: RequestLike | undefined, options: ContextOptions): Built;
+/**
+ * What `authenticate` answered for `janus`'s request, or `undefined` when it
+ * never ran — nothing asked `user()` or `session()`, or the context was not
+ * built here. Never runs it.
+ */
+export declare function answerOf(janus: object): Promise<Authenticated<AnyUser> | null> | undefined;
 /**
  * The clock `@fresh` and `requireFresh()` read the time from: the one given
  * to `useJanus({ clock })`, or the system's.

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,WAAW,EAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,iFAAiF;AACjF,MAAM,MAAM,KAAK,GAAG,CACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC9D,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,KAChC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,qEAAqE;AACrE,KAAK,OAAO,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,KAAK,SAAS,GAAG;IAChB,YAAY,CACX,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAClC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;CAC1C,CAAC;AAEF,KAAK,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAa9C,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,EAAE,cAAc,GACrB,KAAK,CAoCP;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,KAAK,GAAG,IAAI,CAMlE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAQ3D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,WAAW,EAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,iFAAiF;AACjF,MAAM,MAAM,KAAK,GAAG,CACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC9D,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,KAChC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,qEAAqE;AACrE,KAAK,OAAO,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,KAAK,SAAS,GAAG;IAChB,YAAY,CACX,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAClC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;CAC1C,CAAC;AAEF,KAAK,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAuB9C,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,EAAE,cAAc,GACrB,KAAK,CAqCP;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACvB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,CAEpD;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,KAAK,GAAG,IAAI,CAMlE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAQ3D"}

package/dist/errors.d.ts

@@ -26,6 +26,22 @@ export declare function janusGraphQLError(error: JanusError): GraphQLError;
 export declare function rethrown(error: unknown): never;
 /** Yoga's and envelop's `maskError` signature. */
 export type MaskError = (error: unknown, message: string, isDev?: boolean) => Error;
+/** What `janusMaskError()` takes. */
+export interface JanusMaskErrorOptions {
+    /**
+     * Called once with every `JanusError` answered 5xx — `STORE_FAILED`,
+     * `UNSUPPORTED`, `PERMISSION_DEPTH` — whichever path it took: a
+     * directive, `requireUser()`, `can()`, or a resolver that let it through.
+     * Its `slot`, `operation`, `reason` and cause are for your logs; the
+     * response never carries them.
+     *
+     * **It cannot change the answer**: one that throws, or rejects, is a
+     * `process.emitWarning`, and the 503 is sent all the same.
+     */
+    readonly report?: (error: JanusError) => unknown;
+    /** Every error that is not a `JanusError`; see `janusMaskError()`. */
+    readonly fallback?: MaskError;
+}
 /**
  * Yoga's `maskedErrors.maskError`: a `JanusError` a resolver let through is
  * answered with its code and status — `STORE_FAILED` as 503, never masked
@@ -33,12 +49,19 @@ export type MaskError = (error: unknown, message: string, isDev?: boolean) => Er
  *
  * Without a `fallback`, a `GraphQLError` is kept and anything else becomes
  * `message`, with no detail. Pass Yoga's own `maskError` to keep its
- * development-mode details:
+ * development-mode details — as the options' `fallback`, or alone, as
+ * before `report` existed:
  *
  * ```ts
  * import { createYoga, maskError } from 'graphql-yoga';
- * createYoga({ schema, plugins, maskedErrors: { maskError: janusMaskError(maskError) } });
+ * createYoga({
+ *   schema,
+ *   plugins,
+ *   maskedErrors: {
+ *     maskError: janusMaskError({ report: (error) => logger.error(error), fallback: maskError }),
+ *   },
+ * });
  * ```
  */
-export declare function janusMaskError(fallback?: MaskError): MaskError;
+export declare function janusMaskError(options?: JanusMaskErrorOptions | MaskError): MaskError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAmC,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;AAEvE,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAKvE;AAaD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAQjE;AA4CD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE9C;AAED,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,CACvB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,KACX,KAAK,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,QAAQ,GAAE,SAAkB,GAAG,SAAS,CAiBtE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAmC,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;AAEvE,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAKvE;AAaD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAQjE;AA4CD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE9C;AAED,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,CACvB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,KACX,KAAK,CAAC;AAEX,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IACjD,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC7B,OAAO,GAAE,qBAAqB,GAAG,SAAc,GAC7C,SAAS,CAqBX"}

package/dist/index.d.ts

@@ -9,16 +9,23 @@
  * - `applyJanusDirectives(schema, { auth })` — the schema transform alone;
  * - `requireUser(ctx, { type? })`, `requireFresh(ctx, maxAge)` and
  *   `can(ctx, permission, object)` — the calls a resolver makes itself;
- * - `janusMaskError(fallback?)` — Yoga's `maskError`: a `JanusError` as its
- *   code and status, `STORE_FAILED` as 503 and never as 401 or 403.
+ * - `janusMaskError({ report?, fallback? })` — Yoga's `maskError`: a
+ *   `JanusError` as its code and status, `STORE_FAILED` as 503 and never as
+ *   401 or 403, and every 5xx handed to `report`.
  * - `janusGraphQLError(error)` — a `JanusError` as the `GraphQLError` the
  *   client reads, and `denial(code, message?)` — a denial of your own.
+ * - `janusConnection({ auth, access?, type?, clock?, upgrade? })` —
+ *   subscriptions over graphql-ws: `onConnect` and `context` for its
+ *   `useServer()`, a connection authenticated from its `connectionParams`
+ *   or its upgrade request.
  *
  * It defines no error class: a denial is a `GraphQLError`, and what it lets
  * through is `@nxgt/janus`'s own.
  */
+export { janusConnection } from './connection/connection';
+export type { ConnectionContext, JanusConnection, JanusConnectionOptions, } from './connection/types';
 export { applyJanusDirectives, type JanusDirectivesOptions, } from './directives/apply';
-export { type DenialCode, denial, janusGraphQLError, janusMaskError, type MaskError, } from './errors';
+export { type DenialCode, denial, type JanusMaskErrorOptions, janusGraphQLError, janusMaskError, type MaskError, } from './errors';
 export { requireFresh } from './fresh';
 export { can, type RequireUserOptions, requireUser } from './helpers';
 export { useJanus } from './plugin';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,oBAAoB,EACpB,KAAK,sBAAsB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,KAAK,UAAU,EACf,MAAM,EACN,iBAAiB,EACjB,cAAc,EACd,KAAK,SAAS,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,KAAK,kBAAkB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,YAAY,EACX,IAAI,EACJ,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,UAAU,GACV,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EACX,iBAAiB,EACjB,eAAe,EACf,sBAAsB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,oBAAoB,EACpB,KAAK,sBAAsB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,KAAK,UAAU,EACf,MAAM,EACN,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,cAAc,EACd,KAAK,SAAS,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,KAAK,kBAAkB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,YAAY,EACX,IAAI,EACJ,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,UAAU,GACV,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}