@nxgt/janus-graphql 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,8 @@
 
 [`@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
+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.
 
@@ -77,20 +78,22 @@ 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 |
 | `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 |
 
@@ -108,6 +111,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 +127,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 +142,8 @@ 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).
 
 ## Errors
 
@@ -143,8 +156,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, … |
@@ -206,19 +220,31 @@ response with several errors: [the errors guide](docs/guide/errors.md).
 - **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).
+- **`@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, 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
+Twenty-nine 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,7 +265,10 @@ 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`.
+  `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.
 

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,6 +33,7 @@ export interface ContextOptions {
         readonly can: unknown;
     } | undefined;
     readonly type?: string | undefined;
+    readonly clock?: Clock | undefined;
 }
 /**
  * `ctx.janus` for one request. `authenticate` runs the first time `user()`
@@ -44,6 +45,11 @@ export interface ContextOptions {
  * 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;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"}

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,14 +1,14 @@
 /**
  * `@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
@@ -19,6 +19,7 @@
  */
 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';

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

package/dist/index.js

@@ -2,6 +2,11 @@
 import { MapperKind, mapSchema } from "@graphql-tools/utils";
 import { defaultFieldResolver } from "graphql";
 
+// src/context.ts
+import {
+  systemClock
+} from "@nxgt/janus";
+
 // src/memo.ts
 var NOTATION = /[@#]/;
 function keyOf(subject, permission, object, options) {
@@ -32,8 +37,9 @@ function memoized(access) {
 
 // src/context.ts
 var checks = new WeakMap;
+var clocks = new WeakMap;
 function createJanusContext(request, options) {
-  const { auth, access, type } = options;
+  const { auth, access, type, clock } = options;
   let answer;
   let asked = false;
   const authenticated = () => {
@@ -55,8 +61,13 @@ function createJanusContext(request, options) {
       fresh: (...args) => can.apply(access, args)
     });
   }
+  if (clock !== undefined)
+    clocks.set(janus, clock);
   return janus;
 }
+function clockOf(janus) {
+  return clocks.get(janus) ?? systemClock;
+}
 function checkOf(janus, fresh = false) {
   const built = checks.get(janus);
   if (built !== undefined)
@@ -165,6 +176,30 @@ function masked(error, message) {
   });
 }
 
+// src/fresh.ts
+import {
+  assertFresh,
+  parseDuration
+} from "@nxgt/janus";
+async function freshSession(janus, maxAgeMs) {
+  const session = await janus.session().then(undefined, rethrown);
+  if (session === null)
+    throw denial("UNAUTHENTICATED");
+  try {
+    assertFresh(session, maxAgeMs, clockOf(janus));
+  } catch (error) {
+    rethrown(error);
+  }
+  return session;
+}
+async function requireFresh(ctx, maxAge) {
+  if (typeof maxAge !== "string") {
+    throw new TypeError("requireFresh(): maxAge is a duration with its unit, such as '10m' — a bare number would be milliseconds, where @fresh reads seconds");
+  }
+  const maxAgeMs = parseDuration(maxAge, "requireFresh(): maxAge");
+  return freshSession(janusOf(ctx, "requireFresh()"), maxAgeMs);
+}
+
 // src/directives/permission/path.ts
 var NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
 function parsePath(text) {
@@ -278,6 +313,9 @@ async function enforce(requirement, { parent, args, ctx, fresh }) {
   if (requirement.types !== null && !requirement.types.has(user.type)) {
     throw denial("FORBIDDEN");
   }
+  if (requirement.maxAgeMs !== null) {
+    await freshSession(janus, requirement.maxAgeMs);
+  }
   const [first] = requirement.permissions;
   if (first === undefined)
     return;
@@ -326,12 +364,16 @@ function locations(schema, field, fieldName, typeName) {
 }
 function readField(schema, field, fieldName, typeName) {
   const authenticated = [];
+  const fresh = [];
   const permission = [];
   for (const { where, onType, node } of locations(schema, field, fieldName, typeName)) {
     for (const args of getDirective(schema, node, "authenticated") ?? []) {
       const types = args.type;
       authenticated.push({ where, types: types ?? null });
     }
+    for (const args of getDirective(schema, node, "fresh") ?? []) {
+      fresh.push({ where, maxAge: args.maxAge });
+    }
     for (const args of getDirective(schema, node, "permission") ?? []) {
       permission.push({
         where,
@@ -343,7 +385,7 @@ function readField(schema, field, fieldName, typeName) {
       });
     }
   }
-  return { authenticated, permission };
+  return { authenticated, fresh, permission };
 }
 
 // src/directives/words.ts
@@ -473,15 +515,15 @@ function conditionOf(model, use, wiring, refuse) {
 
 // src/directives/validate.ts
 function requirementOf(field, directives, known, wiring) {
-  const { authenticated, permission } = directives;
-  if (authenticated.length === 0 && permission.length === 0)
+  const { authenticated, fresh, permission } = directives;
+  const [name, first] = firstOf(directives);
+  if (first === undefined)
     return null;
-  const [first] = authenticated.length > 0 ? authenticated : permission;
-  const name = authenticated.length > 0 ? "@authenticated" : "@permission";
   return {
     where: field.name,
-    label: `${name} on ${on(first?.where ?? field.name, field.name)}`,
+    label: `${name} on ${on(first.where, field.name)}`,
     types: typesOf(field.name, authenticated, known),
+    maxAgeMs: maxAgeOf(field.name, fresh),
     permissions: permission.map((use) => permissionCheckOf(use, field, wiring))
   };
 }
@@ -505,6 +547,27 @@ function typesOf(field, uses, known) {
   }
   return types;
 }
+function firstOf({
+  authenticated,
+  fresh,
+  permission
+}) {
+  if (authenticated.length > 0)
+    return ["@authenticated", authenticated[0]];
+  if (fresh.length > 0)
+    return ["@fresh", fresh[0]];
+  return ["@permission", permission[0]];
+}
+function maxAgeOf(field, uses) {
+  let seconds = null;
+  for (const { where, maxAge } of uses) {
+    if (!Number.isSafeInteger(maxAge) || maxAge <= 0) {
+      throw new TypeError(`${PREFIX}: @fresh on ${on(where, field)} asks maxAge: ${maxAge} — write a number of seconds above zero, such as maxAge: 600 for ten minutes`);
+    }
+    seconds = seconds === null ? maxAge : Math.min(seconds, maxAge);
+  }
+  return seconds === null ? null : seconds * 1000;
+}
 
 // src/directives/apply.ts
 function applyJanusDirectives(schema, options) {
@@ -517,10 +580,15 @@ function applyJanusDirectives(schema, options) {
       }, readField(schema, field, fieldName, typeName), known, options);
       if (requirement === null)
         return field;
+      const resolve = field.resolve ?? defaultFieldResolver;
+      if (field.subscribe === undefined) {
+        return { ...field, resolve: guarded(resolve, requirement) };
+      }
+      const onEvent = { ...requirement, maxAgeMs: null };
       return {
         ...field,
-        resolve: guarded(field.resolve ?? defaultFieldResolver, requirement),
-        ...field.subscribe === undefined ? {} : { subscribe: guarded(field.subscribe, requirement) }
+        subscribe: guarded(field.subscribe, requirement),
+        resolve: guarded(resolve, onEvent)
       };
     }
   });
@@ -559,13 +627,16 @@ async function can(ctx, permission, object, ...options) {
 }
 // src/plugin.ts
 function useJanus(options) {
-  const { auth, access, type, loaders, conditions } = 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");
+  }
   const applied = new WeakSet;
   return {
     onContextBuilding: ({ context, extendContext }) => {
@@ -573,7 +644,8 @@ function useJanus(options) {
       const janus = createJanusContext(request, {
         auth,
         access,
-        type
+        type,
+        clock
       });
       extendContext({ janus });
     },
@@ -602,6 +674,14 @@ directive @authenticated(
 	type: [String!]
 ) on OBJECT | INTERFACE | FIELD_DEFINITION
 
+"""
+Only a session that proved who it is less than \`maxAge\` seconds ago reaches
+this field, or every field of this type or interface: signed in, or confirmed
+since by a step-up. Anonymous is answered UNAUTHENTICATED, an older session
+STEP_UP_REQUIRED. Where several apply, the smallest \`maxAge\` holds.
+"""
+directive @fresh(maxAge: Int!) on OBJECT | INTERFACE | FIELD_DEFINITION
+
 """
 What a denied \`@permission\` answers.
 """
@@ -637,9 +717,10 @@ export {
   janusGraphQLError,
   janusMaskError,
   janusTypeDefs,
+  requireFresh,
   requireUser,
   useJanus
 };
 
-//# debugId=D0DEC0D35AFB92A464756E2164756E21
+//# debugId=50FC1B1149A482D964756E2164756E21
 //# sourceMappingURL=index.js.map