@nxgt/janus-graphql 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# @nxgt/janus-graphql
+
+[`@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.
+
+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
+on envelop.
+
+```ts
+import { janusMaskError, janusTypeDefs, type JanusContext, useJanus } from '@nxgt/janus-graphql';
+import { createSchema, createYoga, type YogaInitialContext } from 'graphql-yoga';
+import { access } from './access'; // what permissions() answered
+import { auth } from './auth'; // what janus() answered
+
+type Context = YogaInitialContext & JanusContext<typeof auth, typeof access>;
+
+const typeDefs = /* GraphQL */ `
+	type Query {
+		me: User @authenticated
+		ward(id: ID!): Ward @permission(name: "enter", type: "ward")
+	}
+	type User { id: ID!, email: String }
+	type Ward { id: ID!, name: String, roster: [String!] @authenticated(type: ["staff"]) }
+`;
+
+export const yoga = createYoga({
+	schema: createSchema({
+		typeDefs: [janusTypeDefs, typeDefs],
+		resolvers: {
+			Query: {
+				me: async (_: unknown, __: unknown, ctx: Context) => ctx.janus.user(), // never null here
+				ward: (_: unknown, { id }: { id: string }) => wards.find(id), // only for a user who may enter it
+			},
+		},
+	}),
+	plugins: [useJanus({ auth, access })],
+	maskedErrors: { maskError: janusMaskError() }, // STORE_FAILED → 503, not "Unexpected error."
+});
+```
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/janus-graphql @nxgt/janus graphql @graphql-tools/utils @envelop/core
+bun add -d typescript        # 6
+```
+
+Every peer is required:
+
+| Peer | Range | Why |
+| --- | --- | --- |
+| `@nxgt/janus` | the minor released beside it — `peerDependencies` states the range | A **peer**, never a dependency: this package defines no error class, so the `JanusError` a resolver throws is the one you import |
+| `graphql` | `^16.9.0 \|\| ^17.0.0` | The schema and `GraphQLError` are yours; a second copy of `graphql` fails every schema |
+| `@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` |
+
+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.
+
+Like `@nxgt/janus`, it expects `"moduleResolution": "bundler"`: the
+declarations import without extensions, so `nodenext` is not supported.
+
+The SDL ships twice: `janusTypeDefs`, a string for `createSchema`, and
+`graphql/janus.graphqls` in the package, for a code generator or an editor
+that reads files — `node_modules/@nxgt/janus-graphql/graphql/janus.graphqls`.
+
+## API
+
+| 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` |
+| `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` |
+| `@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 |
+| `@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` |
+| `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 |
+| `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 |
+
+## Directives
+
+```graphql
+type Query {
+	me: User @authenticated                                        # any signed-in user
+	record(id: ID!): Record @permission(name: "view", type: "record") # args.id
+	records(ids: [ID!]!): [Record!]!
+		@permission(name: "view", type: "record", id: "args.ids")     # every id
+}
+
+type Record @permission(name: "view", type: "record") {             # parent.id: the record itself
+	title: String
+	billing: Billing @permission(name: "manage", type: "record", onDeny: FORBIDDEN)
+}
+```
+
+```ts
+useJanus({
+	auth,
+	access,
+	loaders: { record: (id, ctx) => records.find(id) }, // record has a fromField: an id alone is not enough
+	conditions: { record: (record, ctx: Context) => ({ onShift: ctx.shift.open }) }, // the ctx of a when() record's permissions reach
+});
+```
+
+Each runs before the resolver, which a refused request never reaches.
+`@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
+directive that applies must hold — the field's, its type's, its
+interfaces' — asked outermost first, so a type's `NOT_FOUND` answers before
+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).
+
+## Errors
+
+This package defines **no error class**. A denial is a `GraphQLError`, and
+every one carries a `code` and the HTTP status Yoga answers with:
+
+```json
+{ "errors": [{ "message": "Not signed in", "path": ["me"], "extensions": { "code": "UNAUTHENTICATED" } }] }
+```
+
+| Code | Status | When |
+| --- | --- | --- |
+| `UNAUTHENTICATED` | 401 | An anonymous request reached a guarded field, or `requireUser()` |
+| `FORBIDDEN` | 403 | A user of a type the directive or `requireUser()` does not name; a `@permission(onDeny: FORBIDDEN)` denied |
+| `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, … |
+
+The status sits in `extensions.http.status`, which Yoga reads to answer the
+HTTP response and strips from the body. `USER_INVALID` adds `issues`,
+`PASSWORD_TOO_SHORT` `minLength` and `CODE_INVALID` `attemptsLeft`; nothing
+else — never `reason`, `login`, a hash prefix or a cause. The message is a
+fixed one per status, never the core's: read `code`. Detail, and the status of a
+response with several errors: [the errors guide](docs/guide/errors.md).
+
+## Traps
+
+- **Without `janusMaskError()`, a `JanusError` from a resolver is Yoga's
+  masked 500.** A guarded field and `requireUser()` answer an outage 503 on
+  their own; `ctx.janus.user()` read directly, or `auth.signIn` in a mutation,
+  does not. Wire `maskedErrors: { maskError: janusMaskError() }`.
+- **`ctx.janus.user()` is `null` where no directive guards the field.** Read
+  it only where anonymous is a valid answer, or call `requireUser(ctx)`.
+- **A type's `@authenticated` guards its fields, not the field that returns
+  it.** `type Ward @authenticated` leaves `Query.ward` open: its resolver runs
+  for an anonymous request, and the error lands on `ward.name`. Put the
+  directive on the field too — or call `requireUser()`, as above — when the
+  lookup itself must not run.
+- **One refused field sets the status of the whole response.** Yoga answers
+  the highest `extensions.http.status` among the errors, so `{ open me }`
+  from an anonymous request is a 401 whose `data` still holds `open`. A client
+  reads `data` and `errors`, not only the status.
+- **A renewed session is not sent back as a cookie.** `authenticate` renews
+  a sliding session in passing, and nothing here sets `Set-Cookie` on the
+  GraphQL response: a browser keeps the cookie with its old expiry. Sign in
+  and renew through your HTTP routes, or send a bearer token.
+- **`useJanus({ type })` narrows the whole server.** A user of any other type
+  is anonymous everywhere, and a directive naming another type is refused
+  when the schema is built.
+- **On a field, `@permission` reads `args.id` — even on a field of the
+  object.** `type Record { notes: String @permission(name: "view", type:
+  "record") }` is refused at start-up: `notes` takes no `id`. Write it on the
+  type, whose default is `parent.id`, or say `id: "parent.id"`.
+- **A `FORBIDDEN` tells the user the object exists.** Keep `NOT_FOUND`, the
+  default, on anything reached by an id the client chose; use
+  `onDeny: FORBIDDEN` on a field of an object the user may already see.
+- **The parent must carry the fields its `fromField`s read.** A type-level
+  `@permission` checks the parent itself, so a resolver answering
+  `{ id, title }` for a record whose `doctors` read `doctorId` denies every
+  doctor. Answer the field, or read the id from `args` with a loader.
+- **A loader's own error is a 500.** `@permission` answers a `JanusError`
+  with its status, but a driver's error thrown by a loader is masked like any
+  other: throw `StoreFailure` for an outage, so it is a 503.
+- **A request remembers its checks.** The same object, permission and user
+  asked twice in one request is one check — so a mutation that grants or
+  revokes, then asks again in the same request, reads the answer from
+  before the change. Call `access.can` directly there. In a subscription,
+  `@permission` asks afresh on every event; `can(ctx, …)` in its resolver
+  reads the memo — call `ctx.janus.access.can` there.
+- **`@permission` is not a filter.** A list of ids requires the permission
+  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).
+- **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
+- [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
+`@ts-expect-error` case in `test/types/`:
+
+- five in `context.ts`: reading the user or the session where either may be
+  `null` (twice), a field of another user type once `JanusContext` is narrowed,
+  `ctx.janus.access` where `useJanus()` was given none, and a context narrowed
+  to a user type the instance does not know;
+- nine in `helpers.ts`: `requireUser()` — a field of another user type once
+  narrowed, a user type the instance does not know, an empty list of user
+  types — and `can()` — a
+  permission the object's type does not declare, an object type the model
+  does not, an object without a field a `fromField` reads, a condition reached
+  with no `ctx`, a `ctx` of the wrong shape, and a context with no `access`;
+- five in `plugin.ts`: `useJanus()` given a user type the instance does not
+  know, something that is not what `janus()` answered, the `permissions()`
+  instance as `auth`, and `applyJanusDirectives()` without `auth` or narrowed
+  to a user type the instance does not know;
+- five in `wiring.ts`: `useJanus()`'s `loaders` for an object type the model
+  does not declare, a loader answering an object without a field a
+  `fromField` reads, `conditions` for a type no `when()` is reached on, a
+  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.
+
+## Licence
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `ctx.janus`, built once per request by `useJanus()`: a lazy
+ * authentication, and the per-request check `can()` and the directives ask
+ * through.
+ */
+import type { Authenticated, 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: {
+    readonly type: string;
+    readonly id: string;
+} | null, permission: string, object: {
+    readonly type: string;
+    readonly id: string;
+}, options?: {
+    readonly ctx?: unknown;
+}) => Promise<boolean>;
+/** A user as this module reads one: the part every user type has. */
+type AnyUser = {
+    readonly type: string;
+    readonly id: string;
+};
+type LooseAuth = {
+    authenticate(request: RequestLike, options?: {
+        readonly type?: string;
+    }): Promise<Authenticated<AnyUser> | null>;
+};
+type Built = JanusOnContext<AnyUser, unknown>;
+/** What `createJanusContext` reads from `useJanus()`'s options. */
+export interface ContextOptions {
+    readonly auth: LooseAuth;
+    readonly access?: {
+        readonly can: unknown;
+    } | undefined;
+    readonly type?: string | undefined;
+}
+/**
+ * `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
+ * `TypeError` from `user()`, not `null`: anonymous is an answer, and nothing
+ * here asked.
+ */
+export declare function createJanusContext(request: RequestLike | undefined, options: ContextOptions): Built;
+/**
+ * The check `ctx.janus` answers through: the one its context was built
+ * with — `access.can`, memoized for the request (`memo.ts`) — or
+ * `access.can` itself for a context built by hand. `null` when it has no
+ * `access` at all.
+ *
+ * `fresh` skips the memo: a subscription is one request whose checks run
+ * again on every event, and must see a `revoke()` made since it started.
+ */
+export declare function checkOf(janus: object, fresh?: boolean): Check | null;
+/**
+ * `ctx.janus`, or a wiring `TypeError` naming `caller` when nothing put it
+ * there: `useJanus()` is missing from the plugins.
+ */
+export declare function janusOf(ctx: unknown, caller: string): Built;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +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"}

package/dist/directives/apply.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The schema transform: every object field a directive guards gets its
+ * resolver wrapped, once, when the schema is built.
+ */
+import { type GraphQLSchema } from 'graphql';
+type Entries = {
+    readonly [type: string]: ((...args: never[]) => unknown) | undefined;
+};
+/** What `applyJanusDirectives()` takes. */
+export interface JanusDirectivesOptions<T extends string = string> {
+    /** What `janus()` answered: its `types` are the names `type:` may take. */
+    readonly auth: {
+        readonly types: readonly T[];
+    };
+    /** `useJanus({ type })`'s: the one user type the schema's users can have. */
+    readonly type?: NoInfer<T>;
+    /** What `permissions()` answered: its model is what `@permission` may name. Required once a schema uses it. */
+    readonly access?: {
+        readonly model: unknown;
+    } | undefined;
+    /** `useJanus({ loaders })`'s. */
+    readonly loaders?: Entries | undefined;
+    /** `useJanus({ conditions })`'s. */
+    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.
+ *
+ * `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`,
+ * which only `useJanus()` builds.
+ *
+ * **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.
+ */
+export declare function applyJanusDirectives<const T extends string>(schema: GraphQLSchema, options: JanusDirectivesOptions<T>): GraphQLSchema;
+export {};
+//# sourceMappingURL=apply.d.ts.map

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

@@ -0,0 +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"}

package/dist/directives/guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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
+ * denial is a `GraphQLError`; a failure to answer is `SERVICE_UNAVAILABLE`,
+ * never a denial.
+ */
+import type { GraphQLFieldResolver } from 'graphql';
+import type { Requirement } from './validate';
+/** What the field was asked with. */
+export interface Resolving {
+    readonly parent: unknown;
+    readonly args: unknown;
+    readonly ctx: unknown;
+    /** A subscription's: its checks skip the request's memo, and see a revoke. */
+    readonly fresh: boolean;
+}
+/** Refuses the request unless it meets `requirement`. */
+export declare function enforce(requirement: Requirement, { parent, args, ctx, fresh }: Resolving): Promise<void>;
+/** `resolve`, run only once `requirement` is met. */
+export declare function guarded<S, C, A>(resolve: GraphQLFieldResolver<S, C, A>, requirement: Requirement): GraphQLFieldResolver<S, C, A>;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +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"}

package/dist/directives/permission/enforce.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One `@permission`, asked at request time: the objects its `id:` names, each
+ * checked with the request's check — memoized per request — and a denial
+ * unless every one holds. A failure to answer is never a denial.
+ */
+import type { Check } from '../../context';
+import type { PermissionCheck } from './validate';
+type Subject = {
+    readonly type: string;
+    readonly id: string;
+};
+/** What the guard has in hand when it asks. */
+export interface Asking {
+    readonly check: Check;
+    readonly user: Subject;
+    readonly parent: unknown;
+    readonly args: unknown;
+    /** The GraphQL context, which `loaders` and `conditions` receive. */
+    readonly ctx: unknown;
+}
+/** Refuses the request unless `user` holds `permission` on every object its `id:` names. */
+export declare function enforcePermission(permission: PermissionCheck, asking: Asking): Promise<void>;
+export {};
+//# sourceMappingURL=enforce.d.ts.map

package/dist/directives/permission/enforce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../../src/directives/permission/enforce.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,KAAK,OAAO,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,+CAA+C;AAC/C,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACtB;AAED,4FAA4F;AAC5F,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/directives/permission/model.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What `@permission` reads of the permission model when the schema is built:
+ * the object types, the names each declares, whether one reads a field of
+ * its object (`fromField`), and whether a permission reaches a condition
+ * (`when`). Read from `access.model`, as `defineModel()` answered it.
+ */
+/** `access.model`, as this module reads it. */
+export interface ModelLike {
+    readonly types: readonly string[];
+    readonly definition: {
+        readonly types: {
+            readonly [type: string]: {
+                readonly related?: {
+                    readonly [name: string]: unknown;
+                };
+                readonly permits?: {
+                    readonly [name: string]: readonly unknown[];
+                };
+            };
+        };
+    };
+}
+/** `access.model`, or `null` when `access` is not what `permissions()` answered. */
+export declare function modelOf(access: unknown): ModelLike | null;
+/** The relations and permissions `type` declares: what `can()` may be asked. */
+export declare function namesOf(model: ModelLike, type: string): readonly string[];
+/** The fields `type`'s `fromField`s read; empty when it has none. */
+export declare function fieldsOf(model: ModelLike, type: string): readonly string[];
+/**
+ * Whether `can(…, name, { type })` reaches a `when` — through the
+ * permission's rules, the permissions they name, and arrows into other types
+ * — and so needs a `ctx`. What `CtxOf` computes in the compiler.
+ */
+export declare function reachesCondition(model: ModelLike, type: string, name: string, seen?: Set<string>): boolean;
+//# sourceMappingURL=model.d.ts.map

package/dist/directives/permission/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/directives/permission/model.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE;QACpB,QAAQ,CAAC,KAAK,EAAE;YACf,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG;gBACxB,QAAQ,CAAC,OAAO,CAAC,EAAE;oBAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;iBAAE,CAAC;gBACxD,QAAQ,CAAC,OAAO,CAAC,EAAE;oBAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAA;iBAAE,CAAC;aACnE,CAAC;SACF,CAAC;KACF,CAAC;CACF;AAED,oFAAoF;AACpF,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAOzD;AAED,gFAAgF;AAChF,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMzE;AAYD,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAC3B,OAAO,CAiBT"}

package/dist/directives/permission/path.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@permission`'s `id:` — `args.<path>` or `parent.<path>` — parsed when the
+ * schema is built, and read from a request's arguments or parent value when a
+ * field is resolved.
+ */
+/** A parsed `id:`. */
+export interface IdPath {
+    /** As written: `args.id`, `parent.wardId`, `args.input.ids`. */
+    readonly text: string;
+    readonly root: 'args' | 'parent';
+    /** The names after the root, at least one. */
+    readonly segments: readonly string[];
+}
+/** `text` parsed, or `null` when it is not `args.<name>…` or `parent.<name>…`. */
+export declare function parsePath(text: string): IdPath | null;
+/** One object a check is about: its id, and the value that holds it when that value is the object. */
+export interface Target {
+    readonly id: string;
+    /** The value the id was read from, when `id` is its `id` field under `parent`. */
+    readonly holder: object | null;
+}
+/**
+ * The objects `path` names in this request: one, or one per element where a
+ * step reads a list. `null` when a step reads nothing, or an id is not a
+ * string or an integer: the request resolved no object id. An empty list
+ * under `parent` is `null` too — the object's data names nothing to check,
+ * and its fields are not open to everyone for it; under `args` it is the
+ * client asking for nothing, and there is nothing to refuse.
+ */
+export declare function targetsOf(path: IdPath, parent: unknown, args: unknown): readonly Target[] | null;
+//# sourceMappingURL=path.d.ts.map

package/dist/directives/permission/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/directives/permission/path.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sBAAsB;AACtB,MAAM,WAAW,MAAM;IACtB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAID,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOrD;AAED,sGAAsG;AACtG,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACX,SAAS,MAAM,EAAE,GAAG,IAAI,CAiB1B"}

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

@@ -0,0 +1,42 @@
+/**
+ * One `@permission`, checked against the model and the field when the schema
+ * is built, and turned into what the guard asks at request time. Everything
+ * no request could pass is a `TypeError` naming the field.
+ */
+import type { PermissionUse } from '../read';
+import { type IdPath } from './path';
+/** `useJanus({ loaders })`'s entry: the object of a type, by id, or `null`. */
+export type Loader = (id: string, ctx: unknown) => unknown;
+/** `useJanus({ conditions })`'s entry: the `ctx` a type's conditions test. */
+export type Condition = (object: unknown, ctx: unknown) => unknown;
+/** What `@permission` reads from `useJanus()`'s options. */
+export interface PermissionWiring {
+    readonly access?: unknown;
+    readonly loaders?: {
+        readonly [type: string]: unknown;
+    } | undefined;
+    readonly conditions?: {
+        readonly [type: string]: unknown;
+    } | undefined;
+}
+/** One `@permission`, as the guard asks it. */
+export interface PermissionCheck {
+    /** `@permission on Record (read by Record.title)`, for the messages. */
+    readonly label: string;
+    readonly name: string;
+    readonly type: string;
+    readonly onDeny: 'NOT_FOUND' | 'FORBIDDEN';
+    readonly path: IdPath;
+    /** Loads an object named by id alone; `null` passes `{ type, id }`. */
+    readonly load: Loader | null;
+    /** Answers the check's `ctx`; `null` when no condition is reachable. */
+    readonly condition: Condition | null;
+}
+/** The field a directive is read for: `Type.field`, and the arguments it takes. */
+export interface FieldShape {
+    readonly name: string;
+    readonly args: readonly string[];
+}
+/** `use`, checked, or a `TypeError` naming the field. */
+export declare function permissionCheckOf(use: PermissionUse, field: FieldShape, wiring: PermissionWiring): PermissionCheck;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/directives/permission/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAS7C,OAAO,EAAE,KAAK,MAAM,EAAa,MAAM,QAAQ,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,MAAM,MAAM,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;AAC3D,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;AAEnE,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;CACvE;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;CACrC;AAED,mFAAmF;AACnF,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,gBAAgB,GACtB,eAAe,CAoCjB"}

package/dist/directives/read.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reads the directives that apply to one object field: its own, its object
+ * type's, and those of every interface the type implements — on the
+ * interface itself and on the interface's field of the same name. Reads, and
+ * decides nothing: `validate.ts` decides what they add up to.
+ */
+import type { GraphQLFieldConfig, GraphQLSchema } from 'graphql';
+/** One `@authenticated`, and where it was written. */
+export interface AuthenticatedUse {
+    /** `Type.field`, `Type`, `Interface.field` or `Interface`. */
+    readonly where: string;
+    /** Its `type:` argument, or `null` when it names none: any signed-in user. */
+    readonly types: readonly string[] | null;
+}
+/** One `@permission`, as written, and where. */
+export interface PermissionUse {
+    /** `Type.field`, `Type`, `Interface.field` or `Interface`. */
+    readonly where: string;
+    /** Written on a type or an interface, rather than on a field. */
+    readonly onType: boolean;
+    readonly name: string;
+    readonly type: string;
+    /** Its `id:` argument, or `null` when absent. */
+    readonly id: string | null;
+    readonly onDeny: 'NOT_FOUND' | 'FORBIDDEN';
+}
+/** Everything written on one field's locations. */
+export interface FieldDirectives {
+    readonly authenticated: readonly AuthenticatedUse[];
+    /** 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. */
+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

@@ -0,0 +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"}

package/dist/directives/validate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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`).
+ */
+import { type FieldShape, type PermissionCheck, type PermissionWiring } from './permission/validate';
+import type { FieldDirectives } from './read';
+/** What a field requires before its resolver runs. */
+export interface Requirement {
+    /** `Type.field`, for the messages. */
+    readonly where: string;
+    /** The directive a missing `ctx.janus` is reported against. */
+    readonly label: string;
+    /**
+     * The user types allowed, every `type:` intersected; `null` when none
+     * narrows it: any signed-in user.
+     */
+    readonly types: ReadonlySet<string> | null;
+    /** The permissions asked after that, in order: every one must hold. */
+    readonly permissions: readonly PermissionCheck[];
+}
+/** The user types a schema may name: `auth.types`, or the one `useJanus({ type })` keeps. */
+export interface Known {
+    readonly types: readonly string[];
+}
+/**
+ * The requirement of one field, or `null` when nothing guards it. Throws a
+ * `TypeError` naming the field for a directive no request could pass.
+ */
+export declare function requirementOf(field: FieldShape, directives: FieldDirectives, known: Known, wiring: PermissionWiring): Requirement | null;
+//# sourceMappingURL=validate.d.ts.map