@nxgt/janus-graphql 0.2.0 → 0.3.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.
@@ -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 |
+| `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(fallback?)` | Yoga's `maskedErrors.maskError`: a `JanusError` a resolver let through answered with its code and status; anything else to `fallback` |
 | `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` | 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
@@ -218,8 +260,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 +291,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-five 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
@@ -268,9 +321,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,13 +34,16 @@ 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.
  */

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;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;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,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"}

package/dist/index.d.ts

@@ -13,10 +13,16 @@
  *   code and status, `STORE_FAILED` as 503 and never as 401 or 403.
  * - `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 { requireFresh } from './fresh';

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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,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"}

package/dist/index.js

@@ -1,7 +1,3 @@
-// src/directives/apply.ts
-import { MapperKind, mapSchema } from "@graphql-tools/utils";
-import { defaultFieldResolver } from "graphql";
-
 // src/context.ts
 import {
   systemClock
@@ -39,13 +35,13 @@ function memoized(access) {
 var checks = new WeakMap;
 var clocks = new WeakMap;
 function createJanusContext(request, options) {
-  const { auth, access, type, clock } = options;
+  const { auth, access, type, clock, caller = "useJanus()" } = options;
   let answer;
   let asked = false;
   const authenticated = () => {
     if (!asked) {
       asked = true;
-      answer = request === undefined ? Promise.reject(new TypeError("useJanus(): the GraphQL context has no request to authenticate — build the context from an HTTP request")) : auth.authenticate(request, type === undefined ? undefined : { type });
+      answer = request === undefined ? Promise.reject(new TypeError(`${caller}: the GraphQL context has no request to authenticate — build the context from an HTTP request, or accept a graphql-ws connection with janusConnection().onConnect`)) : auth.authenticate(request, type === undefined ? undefined : { type });
     }
     return answer;
   };
@@ -83,6 +79,83 @@ function janusOf(ctx, caller) {
   return janus;
 }
 
+// src/options.ts
+function checkWiring(caller, { auth, access, clock }) {
+  if (typeof auth?.authenticate !== "function") {
+    throw new TypeError(`${caller}: auth is not what janus() answered — pass { auth }`);
+  }
+  if (access !== undefined && typeof access?.can !== "function") {
+    throw new TypeError(`${caller}: access is not what permissions() answered — pass { auth, access }`);
+  }
+  if (clock !== undefined && typeof clock?.now !== "function") {
+    throw new TypeError(`${caller}: clock is not a Clock — pass the clock given to janus(), or leave it out for the system clock`);
+  }
+}
+
+// src/connection/credential.ts
+var BEARER = /^\s*bearer(?:\s|$)/i;
+function credentialOf(ctx, upgrade) {
+  const params = ctx.connectionParams;
+  if (params !== undefined && Object.hasOwn(params, "authorization")) {
+    const { authorization } = params;
+    if (typeof authorization !== "string")
+      return null;
+    if (BEARER.test(authorization))
+      return { authorization };
+  }
+  const request = upgrade === undefined ? ctx.extra?.request : upgrade(ctx);
+  return request ?? null;
+}
+var accepted = new WeakMap;
+function accept(ctx, credential) {
+  const { extra } = ctx;
+  if (typeof extra !== "object" || extra === null) {
+    throw new TypeError("janusConnection(): the connection's extra is not an object — pass the context graphql-ws gave onConnect");
+  }
+  accepted.set(extra, credential);
+}
+function acceptedOf(context) {
+  const extra = context?.extra;
+  if (typeof extra !== "object" || extra === null)
+    return;
+  return accepted.get(extra);
+}
+
+// src/connection/connection.ts
+function janusConnection(options) {
+  const { auth, access, type, clock } = options;
+  checkWiring("janusConnection()", { auth, access, clock });
+  if (options.upgrade !== undefined && typeof options.upgrade !== "function") {
+    throw new TypeError("janusConnection(): upgrade is not a function — pass (ctx) => the upgrade request, or leave it out to read ctx.extra.request");
+  }
+  const upgrade = options.upgrade?.bind(options);
+  const wiring = {
+    auth,
+    access,
+    type,
+    clock,
+    caller: "janusConnection().context"
+  };
+  return {
+    onConnect: async (ctx) => {
+      const credential = credentialOf(ctx, upgrade);
+      if (credential === null)
+        return false;
+      const current = await auth.authenticate(credential, type === undefined ? undefined : { type });
+      if (current === null)
+        return false;
+      accept(ctx, credential);
+      return true;
+    },
+    context: (ctx) => ({
+      janus: createJanusContext(acceptedOf(ctx), wiring)
+    })
+  };
+}
+// src/directives/apply.ts
+import { MapperKind, mapSchema } from "@graphql-tools/utils";
+import { defaultFieldResolver } from "graphql";
+
 // src/errors.ts
 import { JanusError, statusOf } from "@nxgt/janus";
 import { GraphQLError } from "graphql";
@@ -628,20 +701,12 @@ async function can(ctx, permission, object, ...options) {
 // src/plugin.ts
 function useJanus(options) {
   const { auth, access, type, clock, loaders, conditions } = options;
-  if (typeof auth?.authenticate !== "function") {
-    throw new TypeError("useJanus(): auth is not what janus() answered — pass { auth }");
-  }
-  if (access !== undefined && typeof access?.can !== "function") {
-    throw new TypeError("useJanus(): access is not what permissions() answered — pass { auth, access }");
-  }
-  if (clock !== undefined && typeof clock?.now !== "function") {
-    throw new TypeError("useJanus(): clock is not a Clock — pass the clock given to janus(), or leave it out for the system clock");
-  }
+  checkWiring("useJanus()", { auth, access, clock });
   const applied = new WeakSet;
   return {
     onContextBuilding: ({ context, extendContext }) => {
       const { request } = context;
-      const janus = createJanusContext(request, {
+      const janus = createJanusContext(request ?? acceptedOf(context), {
         auth,
         access,
         type,
@@ -714,6 +779,7 @@ export {
   applyJanusDirectives,
   can,
   denial,
+  janusConnection,
   janusGraphQLError,
   janusMaskError,
   janusTypeDefs,
@@ -722,5 +788,5 @@ export {
   useJanus
 };
 
-//# debugId=50FC1B1149A482D964756E2164756E21
+//# debugId=C6BF0BFA8BF13A9C64756E2164756E21
 //# sourceMappingURL=index.js.map