@nxgt/janus-graphql 0.1.1 → 0.3.0

package/README.md

@@ -2,9 +2,10 @@
 
 [`@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` and `@permission`, and
-every error answered with the status it deserves — an outage as 503, never
-as 401, 403 or 404.
+asks, fields and types guarded by `@authenticated`, `@fresh` and
+`@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
@@ -51,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 |
 | --- | --- | --- |
@@ -60,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.
@@ -77,22 +79,25 @@ that reads files — `node_modules/@nxgt/janus-graphql/graphql/janus.graphqls`.
 
 | Export | What it is |
 | --- | --- |
-| `useJanus({ auth, access?, type?, 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. `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` |
 | `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`, `@permission` and the `JanusPermissionDenial` enum — prefixed, so it never collides with a type of your schema. The same text as `graphql/janus.graphqls` |
+| `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` |
 | `@authenticated(type: [String!])` | On a field, a type or an interface. A signed-in user, of one of the `type`s when it names some. Anonymous: `UNAUTHENTICATED`. Another type: `FORBIDDEN`. Every one that applies — the field's, its type's, its interfaces' — must hold |
+| `@fresh(maxAge: Int!)` | On a field, a type or an interface. A session that proved who it is less than `maxAge` **seconds** ago — signed in, or confirmed since by `auth.stepUp.confirm`. Anonymous: `UNAUTHENTICATED`. Older: `STEP_UP_REQUIRED`, 403. Checked after `@authenticated`, before `@permission`; the smallest `maxAge` that applies holds; on a subscription field, checked when it subscribes |
 | `@permission(name, type, id, onDeny)` | On a field, a type or an interface. A user holding permission `name` on the object of `type` whose id `id` reads — `args.<path>` or `parent.<path>`; `args.id` on a field, `parent.id` on a type. A list requires it on every id. Repeated, every one must hold, in order. Denied: `NOT_FOUND`, or `FORBIDDEN` with `onDeny: FORBIDDEN` |
 | `loaders: { [type]: (id, ctx) => object \| null }` | The object `@permission` checks for an id alone — from `args`, or a parent field other than `id` — required for a type with a `fromField`, whose fields `access.can` reads. `null` answers `NOT_FOUND` |
 | `conditions: { [type]: (object, ctx) => ctx }` | The `ctx` `@permission` passes to `access.can` for a permission that reaches a `when()` |
 | `applyJanusDirectives(schema, { auth, type?, access?, loaders?, conditions? })` | The schema transform alone — what `useJanus()` runs — to check a schema in a test or a build script. Throws a `TypeError` naming the field for a directive no request could pass. Its guards read `ctx.janus`, which only `useJanus()` builds |
 | `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 |
+| `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
 
@@ -108,6 +113,10 @@ type Record @permission(name: "view", type: "record") {             # parent.id:
 	title: String
 	billing: Billing @permission(name: "manage", type: "record", onDeny: FORBIDDEN)
 }
+
+type Mutation {
+	changeEmail(email: String!): User @fresh(maxAge: 600)            # signed in or stepped up < 10 min ago
+}
 ```
 
 ```ts
@@ -120,6 +129,12 @@ useJanus({
 ```
 
 Each runs before the resolver, which a refused request never reaches.
+`@fresh(maxAge)` takes **seconds**, and answers an older session
+`STEP_UP_REQUIRED`: the client then calls your two step-up mutations,
+which run `auth.stepUp.request` and `confirm` — shown in
+[the step-up guide](docs/guide/step-up.md) — and sends the request again.
+Every `@authenticated` is checked first, then `@fresh`, then each
+`@permission`, so a stale session asks no permission check.
 `@permission` implies a signed-in user, and asks `access.can` with the parent
 itself when the id is `parent.id`, with what `loaders[type]` answers for an
 id of a type with a `fromField`, and with `{ type, id }` otherwise. Every
@@ -129,8 +144,48 @@ a field's `FORBIDDEN` could tell the object exists. The same question asked
 twice in a request, by two fields or by a directive and `can()`, is one
 check. What no request could pass — an object type or a permission the
 model does not declare, a malformed `id:`, an argument the field does not
-take, a missing loader or condition — is a `TypeError` at start-up naming
-the field. Detail: [the directives guide](docs/guide/directives.md).
+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
 
@@ -143,8 +198,9 @@ every one carries a `code` and the HTTP status Yoga answers with:
 
 | Code | Status | When |
 | --- | --- | --- |
-| `UNAUTHENTICATED` | 401 | An anonymous request reached a guarded field, or `requireUser()` |
+| `UNAUTHENTICATED` | 401 | An anonymous request reached a guarded field, `requireUser()` or `requireFresh()` |
 | `FORBIDDEN` | 403 | A user of a type the directive or `requireUser()` does not name; a `@permission(onDeny: FORBIDDEN)` denied |
+| `STEP_UP_REQUIRED` | 403 | A session older than `@fresh(maxAge)` or `requireFresh()` allows: ask for a step-up, then send the request again |
 | `NOT_FOUND` | 404 | A `@permission` denied — its default — or a loader answered `null`; `denial('NOT_FOUND')` |
 | `SERVICE_UNAVAILABLE` | 503 | A store could not answer — `STORE_FAILED`. **Never a denial** |
 | any other `JanusErrorCode` | its [`statusOf`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/errors.md) | A `JanusError` a resolver let through: `CREDENTIALS_INVALID` 401, `LOGIN_TAKEN` 409, … |
@@ -204,21 +260,44 @@ 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`
+  would read as milliseconds.
+- **`useJanus()` reads the system clock unless given `janus()`'s.** With
+  `janus({ clock: fixedClock(…) })` in a spec and no `useJanus({ clock })`,
+  every session looks as old as the fixed date, and every `@fresh` field
+  answers `STEP_UP_REQUIRED`. Pass the same clock to both.
+- **A subscription field's `@fresh` is checked when it subscribes.** Its
+  events keep coming past `maxAge`; that `@fresh` is not asked again on
+  each one, as `@permission` is. A `@fresh` on the payload's type or its
+  fields is asked on every event, like any field.
 - **A denial of a list field's item fails the whole list** where the item is
   non-null (`[Doctor!]!`), as GraphQL's null propagation always does. Guard
   the list field, or make the item nullable.
 
 ## Documentation
 
-- [Guides](docs/README.md) — the directives, 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-four 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
@@ -239,9 +318,19 @@ Twenty-four plausible mistakes are refused by the compiler, each with a
   does not declare, a loader answering an object without a field a
   `fromField` reads, `conditions` for a type no `when()` is reached on, a
   condition answering a `ctx` of the wrong shape, and `loaders` without
-  `access`.
-
-`plugin.ts` also holds this README's quick start, which must keep compiling.
+  `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`;
+- 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

@@ -3,7 +3,7 @@
  * authentication, and the per-request check `can()` and the directives ask
  * through.
  */
-import type { Authenticated, RequestLike } from '@nxgt/janus';
+import { type Authenticated, type Clock, type RequestLike } from '@nxgt/janus';
 import type { JanusOnContext } from './types';
 /** One check, as `access.can` answers it — loose: the typing is the caller's. */
 export type Check = (subject: {
@@ -33,17 +33,26 @@ export interface ContextOptions {
         readonly can: unknown;
     } | 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;
+/**
+ * The clock `@fresh` and `requireFresh()` read the time from: the one given
+ * to `useJanus({ clock })`, or the system's.
+ */
+export declare function clockOf(janus: object): Clock;
 /**
  * The check `ctx.janus` answers through: the one its context was built
  * with — `access.can`, memoized for the request (`memo.ts`) — or

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,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE9D,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;AAU9C,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;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,EAAE,cAAc,GACrB,KAAK,CAmCP;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/directives/apply.d.ts

@@ -24,11 +24,12 @@ export interface JanusDirectivesOptions<T extends string = string> {
     readonly conditions?: Entries | undefined;
 }
 /**
- * The schema with every field guarded by `@authenticated` or `@permission`
- * — on the field, on its type, or on an interface the type implements —
- * wrapped so its resolver runs only for a signed-in user, of one of the
- * types `type:` names when it names some, holding every permission asked.
- * Every directive that applies must hold.
+ * The schema with every field guarded by `@authenticated`, `@fresh` or
+ * `@permission` — on the field, on its type, or on an interface the type
+ * implements — wrapped so its resolver runs only for a signed-in user, of
+ * one of the types `type:` names when it names some, on a session that
+ * proved who it is less than `maxAge` seconds ago, holding every permission
+ * asked. Every directive that applies must hold.
  *
  * `useJanus()` calls it on every schema it is given. Call it yourself to
  * check a schema without a server: the guards it installs read `ctx.janus`,
@@ -36,10 +37,10 @@ export interface JanusDirectivesOptions<T extends string = string> {
  *
  * **Refuses when the schema is built**, with a `TypeError` naming the
  * field: a user type `auth` does not know, a `type: []`, restrictions no
- * user type meets together; for `@permission`, an object type or a
- * permission the model does not declare, a malformed `id:`, an argument the
- * field does not take, and a loader or a condition's `ctx` it needs and was
- * not given.
+ * user type meets together, a `@fresh` whose `maxAge` is not above zero;
+ * for `@permission`, an object type or a permission the model does not
+ * declare, a malformed `id:`, an argument the field does not take, and a
+ * loader or a condition's `ctx` it needs and was not given.
  */
 export declare function applyJanusDirectives<const T extends string>(schema: GraphQLSchema, options: JanusDirectivesOptions<T>): GraphQLSchema;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/directives/apply.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAMnE,KAAK,OAAO,GAAG;IACd,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACrE,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAChE,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;KAAE,CAAC;IAChD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,+GAA+G;IAC/G,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC1D,iCAAiC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,oCAAoC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC1D,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAChC,aAAa,CAuBf"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/directives/apply.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAMnE,KAAK,OAAO,GAAG;IACd,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACrE,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAChE,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;KAAE,CAAC;IAChD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,+GAA+G;IAC/G,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC1D,iCAAiC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,oCAAoC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC1D,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAChC,aAAa,CA4Bf"}

package/dist/directives/guard.d.ts

@@ -1,6 +1,7 @@
 /**
  * What runs before a guarded field's resolver, at request time: the user,
- * then the requirement — its user types, then each `@permission` in order. A
+ * then the requirement — its user types, the session's freshness, then each
+ * `@permission` in order. A
  * denial is a `GraphQLError`; a failure to answer is `SERVICE_UNAVAILABLE`,
  * never a denial.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/directives/guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,yDAAyD;AACzD,wBAAsB,OAAO,CAC5B,WAAW,EAAE,WAAW,EACxB,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9B,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACtC,WAAW,EAAE,WAAW,GACtB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAU/B"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/directives/guard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAKpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,yDAAyD;AACzD,wBAAsB,OAAO,CAC5B,WAAW,EAAE,WAAW,EACxB,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9B,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACtC,WAAW,EAAE,WAAW,GACtB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAU/B"}

package/dist/directives/read.d.ts

@@ -12,6 +12,13 @@ export interface AuthenticatedUse {
     /** Its `type:` argument, or `null` when it names none: any signed-in user. */
     readonly types: readonly string[] | null;
 }
+/** One `@fresh`, and where it was written. */
+export interface FreshUse {
+    /** `Type.field`, `Type`, `Interface.field` or `Interface`. */
+    readonly where: string;
+    /** Its `maxAge:` argument, in seconds, as written: checked by `validate.ts`. */
+    readonly maxAge: number;
+}
 /** One `@permission`, as written, and where. */
 export interface PermissionUse {
     /** `Type.field`, `Type`, `Interface.field` or `Interface`. */
@@ -27,9 +34,10 @@ export interface PermissionUse {
 /** Everything written on one field's locations. */
 export interface FieldDirectives {
     readonly authenticated: readonly AuthenticatedUse[];
+    readonly fresh: readonly FreshUse[];
     /** In the order they are checked: the type's and interfaces' first, then the field's. */
     readonly permission: readonly PermissionUse[];
 }
-/** Every `@authenticated` and `@permission` that applies to one object field. */
+/** Every `@authenticated`, `@fresh` and `@permission` that applies to one object field. */
 export declare function readField(schema: GraphQLSchema, field: GraphQLFieldConfig<unknown, unknown>, fieldName: string, typeName: string): FieldDirectives;
 //# sourceMappingURL=read.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/directives/read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACX,kBAAkB,EAGlB,aAAa,EACb,MAAM,SAAS,CAAC;AAEjB,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACzC;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC;CAC3C;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpD,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AA0CD,iFAAiF;AACjF,wBAAgB,SAAS,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd,eAAe,CAyBjB"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/directives/read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACX,kBAAkB,EAGlB,aAAa,EACb,MAAM,SAAS,CAAC;AAEjB,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACzC;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC;CAC3C;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AA0CD,2FAA2F;AAC3F,wBAAgB,SAAS,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd,eAAe,CA6BjB"}

package/dist/directives/validate.d.ts

@@ -2,8 +2,8 @@
  * Decides, when the schema is built, what the directives on one field add up
  * to — and refuses with a `TypeError` what no request could ever pass: a user
  * type `auth` does not know, a `type: []`, restrictions that exclude each
- * other, or a `@permission` the model, the field or the wiring cannot answer
- * (`permission/validate.ts`).
+ * other, a `@fresh` whose `maxAge` is not above zero, or a `@permission` the
+ * model, the field or the wiring cannot answer (`permission/validate.ts`).
  */
 import { type FieldShape, type PermissionCheck, type PermissionWiring } from './permission/validate';
 import type { FieldDirectives } from './read';
@@ -18,6 +18,11 @@ export interface Requirement {
      * narrows it: any signed-in user.
      */
     readonly types: ReadonlySet<string> | null;
+    /**
+     * How long ago, in milliseconds, the session may have proved who it is at
+     * most — the smallest `@fresh` that applies; `null` when none does.
+     */
+    readonly maxAgeMs: number | null;
     /** The permissions asked after that, in order: every one must hold. */
     readonly permissions: readonly PermissionCheck[];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/directives/validate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAErB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,QAAQ,CAAC;AAGhE,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC3C,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED,6FAA6F;AAC7F,MAAM,WAAW,KAAK;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,eAAe,EAC3B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,gBAAgB,GACtB,WAAW,GAAG,IAAI,CAWpB"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/directives/validate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAErB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAoB,eAAe,EAAY,MAAM,QAAQ,CAAC;AAG1E,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED,6FAA6F;AAC7F,MAAM,WAAW,KAAK;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,eAAe,EAC3B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,gBAAgB,GACtB,WAAW,GAAG,IAAI,CAWpB"}

package/dist/fresh.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Freshness: whether the request's session proved who it is recently enough
+ * — the check `@fresh` runs before a field, and `requireFresh()` in a
+ * resolver. Both are `@nxgt/janus`'s `assertFresh`, on the clock given to
+ * `useJanus({ clock })`.
+ */
+import { type Duration, type Session } from '@nxgt/janus';
+/**
+ * The request's session, once it proved who it is less than `maxAgeMs` ago
+ * — or a denial: `UNAUTHENTICATED` 401 for an anonymous request,
+ * `STEP_UP_REQUIRED` 403 for an older session. A store that cannot answer is
+ * `SERVICE_UNAVAILABLE` 503, never either of them.
+ */
+export declare function freshSession(janus: {
+    session(): Promise<Session | null>;
+}, maxAgeMs: number): Promise<Session>;
+/**
+ * The request's session, once it proved who it is less than `maxAge` ago —
+ * signed in, or confirmed since by `auth.stepUp.confirm` — or a denial:
+ * `UNAUTHENTICATED` 401 for an anonymous request, `STEP_UP_REQUIRED` 403 for
+ * an older session, which tells the client to ask for a step-up.
+ *
+ * ```ts
+ * await requireFresh(ctx, '10m'); // before changing the e-mail
+ * ```
+ *
+ * `maxAge` is a duration with its unit — `'10m'`, `'600s'` — never a bare
+ * number, which `@nxgt/janus` reads as milliseconds where `@fresh` reads
+ * seconds: a `TypeError`, as any other malformed duration.
+ */
+export declare function requireFresh(ctx: {
+    readonly janus: {
+        user(): Promise<unknown>;
+        session(): Promise<Session | null>;
+    };
+}, maxAge: Exclude<Duration, number>): Promise<Session>;
+//# sourceMappingURL=fresh.d.ts.map

package/dist/fresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fresh.d.ts","sourceRoot":"","sources":["../src/fresh.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEN,KAAK,QAAQ,EAEb,KAAK,OAAO,EACZ,MAAM,aAAa,CAAC;AAIrB;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE;IAAE,OAAO,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;CAAE,EAC7C,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CASlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE;IACJ,QAAQ,CAAC,KAAK,EAAE;QACf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;KACnC,CAAC;CACF,EACD,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC,CAQlB"}

package/dist/index.d.ts

@@ -1,24 +1,31 @@
 /**
  * `@nxgt/janus-graphql` — `@nxgt/janus` in a GraphQL server.
  *
- * - `useJanus({ auth, access?, type?, loaders?, conditions? })` — the
- *   envelop plugin: `ctx.janus` on every request, and the directives —
- *   `@authenticated`, `@permission` — applied to the schema;
+ * - `useJanus({ auth, access?, type?, clock?, loaders?, conditions? })` —
+ *   the envelop plugin: `ctx.janus` on every request, and the directives —
+ *   `@authenticated`, `@fresh`, `@permission` — applied to the schema;
  * - `janusTypeDefs` — the directives' SDL, also shipped as
  *   `graphql/janus.graphqls`;
  * - `applyJanusDirectives(schema, { auth })` — the schema transform alone;
- * - `requireUser(ctx, { type? })` and `can(ctx, permission, object)` — the
- *   calls a resolver makes itself;
+ * - `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.
  * - `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';
 export { can, type RequireUserOptions, requireUser } from './helpers';
 export { useJanus } from './plugin';
 export { janusTypeDefs } from './sdl';