@nxgt/janus-hono 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,205 @@
+# @nxgt/janus-hono
+
+[`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus) in a
+[Hono](https://hono.dev) app: the signed-in user on every request, the session
+cookie set and cleared, a route guarded by a permission, the instances on the
+context to grant and revoke through, and every error answered with the status
+it deserves — an outage as 503, never as 401 or 403.
+
+```ts
+import { janusErrors, sendSession, session, signOut } from '@nxgt/janus-hono';
+import { Hono } from 'hono';
+import { auth } from './auth'; // what janus() answered
+
+const app = new Hono()
+	.post('/sign-in', async (c) => {
+		const { email, password } = await c.req.json();
+		const user = sendSession(c, auth, await auth.signIn({ email, password }));
+		return c.json({ id: user.id }); // the token is in the cookie, not the body
+	})
+	.post('/sign-out', async (c) => {
+		await signOut(c, auth);
+		return c.body(null, 204);
+	})
+	.get('/me', session(auth, { required: true }), (c) =>
+		c.json({ email: c.var.user.email }), // never null here
+	);
+
+app.onError(janusErrors()); // CREDENTIALS_INVALID → 401, STORE_FAILED → 503, …
+```
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/janus-hono @nxgt/janus hono
+```
+
+Every peer is required: `@nxgt/janus`, `hono` (4.13.4 or later) and
+`typescript` (6). `@nxgt/janus` is a **peer**, never a dependency: this package
+defines no error class, so the `JanusError` you catch is the one you import.
+Like `@nxgt/janus`, it expects `"moduleResolution": "bundler"`: the
+declarations import without extensions, so `nodenext` is not supported.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `session(auth, options?)` | Middleware. Reads who the request belongs to — `auth.authenticate(c.req.raw)` — and sets `c.var.user` and `c.var.session`, `null` for an anonymous request. `{ required: true }` answers an anonymous request 401 and types `c.var.user` as never `null`. `{ type: 'staff' }` treats a user of any other type as anonymous. Sends a renewed session's cookie again |
+| `sendSession(c, auth, signedIn)` | Appends the session cookie to the response — after `signUp`, `signIn`, or anything that answered `{ token, session, user }` — and answers the user |
+| `signOut(c, auth)` | Revokes the session the request presents and clears the cookie, whatever the answer. `false` when the request presented no session, or an unknown one |
+| `janusErrors({ report?, fallback? })` | An `app.onError` handler: every `JanusError` answered with `statusOf(code)` and `bodyOf(error)`; anything else to `fallback`, or to Hono's own handling. `report(error, c)` sees every one answered 5xx first — `STORE_FAILED` and the like, for your logs |
+| `statusOf(code)` | The status a code deserves: `STORE_FAILED` 503, `CREDENTIALS_INVALID` 401, `USER_INACTIVE` 403, `LOGIN_TAKEN` 409, … Exhaustive over `JanusErrorCode` |
+| `bodyOf(error)` | `{ code }`, plus `issues` for `USER_INVALID` and `minLength` for `PASSWORD_TOO_SHORT` — what the client can act on, and nothing else |
+| `SessionOptions<Type>` | `{ type?, required? }`, the options of `session()` — for a wrapper of your own |
+| `SessionEnv<typeof auth, Type?, Required?>` | The `Env` `session()` sets, for `new Hono<SessionEnv<typeof auth>>()` |
+| `UserOfAuth<typeof auth>` | The users an instance knows, as a union narrowed by `user.type` |
+| `permission(access, permission, type, load, options?)` | Middleware. Loads the object with `load(c)`, checks `access.can(c.var.user, permission, object)` with `type` added, and sets `c.var.object` to what `load` answered. Anonymous: 401, before loading. `load` answers `null`: 404. A denial: 403. `{ ctx: (c, object) => … }` is required exactly when the permission reaches a condition; `{ subject: (c) => … }` replaces `c.var.user`. One per route |
+| `byParam(name, find)` | A `load` for `permission()`: `find(c.req.param(name))`, or `null` — a 404 — when the route has no such parameter |
+| `bindJanus({ auth?, access? })` | The functions above with the instances bound: `session(options?)`, `sendSession(c, signedIn)` and `signOut(c)` with `auth`; `permission(permission, type, load, options?)` with `access`; `provide()` always |
+| `provide({ auth?, access? })` | Middleware. Sets `c.var.auth` and `c.var.access` to the instances given — only those — for a route that writes users or tuples |
+| `ObjectData<C, Type>`, `PermissionOptions`, `Instances` | The types of `load`'s answer, of `permission()`'s options and of `provide()`'s argument |
+
+The whole status table is in [`@nxgt/janus`'s errors guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/errors.md).
+
+## Permissions
+
+`permission()` guards a route: the object is loaded once, checked, and handed
+to the route. `provide()` puts the instances on the context, so the route that
+creates a record grants its owner through `c.var.access`:
+
+```ts
+import { permission, provide, session } from '@nxgt/janus-hono';
+import { Hono } from 'hono';
+import { access, recordOf } from './access'; // the guide's model, and a loader
+import { auth } from './auth';
+import { records } from './records'; // your own store
+
+const app = new Hono()
+	.use(session(auth), provide({ auth, access }))
+	.get(
+		'/records/:id',
+		permission(access, 'view', 'record', recordOf),
+		(c) => c.json(c.var.object), // your record type, loaded once
+	)
+	.put(
+		'/records/:id',
+		permission(access, 'edit', 'record', recordOf, {
+			ctx: (c, record) => ({ locked: record.locked }), // `edit` reaches a when()
+		}),
+		async (c) => c.json(await records.update(c.var.object.id, await c.req.json())),
+	)
+	.post('/records', session(auth, { type: 'patient', required: true }), async (c) => {
+		const record = await records.create(await c.req.json());
+		await c.var.access.grant({ type: 'record', id: record.id }, 'owner', c.var.user);
+		return c.json(record, 201);
+	});
+```
+
+The model — `owner`, a `doctor` read from the record, `edit` under a condition
+— and `recordOf` are those of the [guarded routes guide](docs/guide/permissions.md). The
+permission, the object type, the fields a `fromField` reads and the `ctx`
+of a condition are typed from the model, as they are for `can()`.
+`janusErrors()` answers the failures of both sides alike — `can()`'s
+`STORE_FAILED` is a 503, never a 403.
+
+### Bound once
+
+`bindJanus({ auth, access })` answers the same functions with the instances
+bound, so no route repeats them — typed exactly as the unbound ones:
+
+```ts
+import { bindJanus, byParam } from '@nxgt/janus-hono';
+
+const j = bindJanus({ auth, access });
+
+const app = new Hono()
+	.use(j.session(), j.provide())
+	.get('/records/:id', j.permission('view', 'record', byParam('id', (id) => records.find(id))), (c) =>
+		c.json(c.var.object),
+	)
+	.post('/sign-out', async (c) => {
+		await j.signOut(c);
+		return c.body(null, 204);
+	});
+```
+
+Only what is given is bound: `bindJanus({ auth })` has no `permission`.
+
+Each side is usable alone. An application that signs users in some other way
+passes `{ subject: (c) => … }` to `permission()`; one without permissions uses
+`session()` and `janusErrors()` only.
+
+## Traps
+
+- **Without `app.onError(janusErrors())`, an outage is Hono's 500.** Not a
+  401 — `session()` never turns a failure into an anonymous request — but not
+  the 503 that tells a client to retry either.
+- **`app.use(session(auth))` on its own line does not type the routes after
+  it.** Hono types a chain, not statements. Chain the calls, or declare the app
+  as `new Hono<SessionEnv<typeof auth>>()`.
+- **A renewed session is sent again only as a cookie, and only to a request
+  that presented one.** A client that sends `Authorization: Bearer` is renewed
+  too — its session token does not change — but it is never handed a cookie it did not
+  ask for. It reads `session.expiresAt` if it needs to.
+- **`required` is typed only for a literal `true`.** A computed `boolean`
+  compiles, and leaves `c.var.user` nullable.
+- **`required` answers 401 with no body and no `WWW-Authenticate`.** Wrap the
+  route yourself for another answer: `session(auth)`, then check
+  `c.var.user === null`.
+- **The cookie is `Secure` by default.** A browser drops it over plain
+  `http://`, `localhost` aside in most browsers. Set `cookie: { secure: false }`
+  in `janus()` for a development server that is not on `localhost`, never in
+  production.
+- **`janusErrors()` logs nothing by itself.** A `STORE_FAILED` is answered 503
+  without a line in your logs unless you pass `report` —
+  `janusErrors({ report: (error) => logger.error(error) })`.
+- **`bodyOf` never carries `reason`, `login` or a cause.** `CREDENTIALS_INVALID`
+  says one thing for an unknown login, a missing password and a wrong one, so a
+  response cannot tell which users exist. Log the error before you answer it
+  if you need the reason: `janusErrors` is a function of `(error, c)` you can
+  wrap.
+- **`load` does not know the route's path.** It takes a plain `Context`:
+  `permission()` is built before Hono attaches it to a route, so
+  `c.req.param('id')` is `string | undefined` there. Answer `null` for a
+  missing id — that is a 404 — or let `byParam('id', find)` do it.
+- **One `permission()` per route.** Both would claim `c.var.object`, so a
+  second throws a `TypeError`. Check a parent object through an arrow in the
+  model.
+- **`permission()` needs `session()` before it**, or `{ subject }`. Without
+  either, it throws a `TypeError` at the first request — a wiring error, not
+  an anonymous 401.
+- **A denial is 403, so it tells that the object exists.** Where that is a
+  leak, load only what the user may see and let `load` answer `null` — a 404.
+
+## Documentation
+
+- [Guides](docs/README.md) — wiring the middleware, the routes of a sign-in, guarded routes
+- [Troubleshooting](docs/troubleshooting.md) — by the symptom or message you see
+- [Roadmap](docs/roadmap.md) — what is next, and what is not planned
+
+## Type safety, counted
+
+Twenty-five plausible mistakes are refused by the compiler, each with a
+`@ts-expect-error` case in `test/types/`:
+
+- six in `session.ts`: reading `c.var.user` where it may be `null` (twice,
+  directly and through `SessionEnv`), a field of another user type, a user type
+  the instance does not know (twice, in `session()` and in `SessionEnv`), and a
+  cookie sent without its session;
+- ten in `permission.ts`: a permission the object type does not declare, an
+  object type the model does not (twice: in a model of one object type and of
+  several, each reported on the misspelled argument), an object loaded without
+  a field a `fromField` reads, a condition reached with no `ctx`, a `ctx` of the
+  wrong shape, a `ctx` where no condition is reachable, a field the loaded
+  object does not have, granting a relation read from a field, and an instance
+  `provide()` was not given;
+- nine in `bind.ts`: the same refusals through `bindJanus()` — a nullable
+  user, an unknown user type, a missing `ctx`, a misspelled permission — a
+  `permission`, `session`, `sendSession` or `signOut` it was not given the
+  instance for, and an `access` that is no `permissions()` instance.
+
+## Licence
+
+MIT

package/dist/bind.d.ts

@@ -0,0 +1,76 @@
+import type { Session } from '@nxgt/janus';
+import type { CheckableOf, ModelConfig, ObjectTypeOf, Permissions } from '@nxgt/janus/permissions';
+import type { Context, MiddlewareHandler } from 'hono';
+import { type Awaitable, type ObjectData, type OptionsArgs } from './permission';
+import { type Auth, type SessionEnv, type SessionOptions, type UserOfAuth } from './session';
+/** `session(auth, options?)`, with `auth` bound: the same three forms. */
+export interface BoundSession<A> {
+    <const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: SessionOptions<T> & {
+        readonly required: true;
+    }): MiddlewareHandler<SessionEnv<A, T, true>>;
+    <const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options?: SessionOptions<T> & {
+        readonly required?: false;
+    }): MiddlewareHandler<SessionEnv<A, T>>;
+    <const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: SessionOptions<T>): MiddlewareHandler<SessionEnv<A, T>>;
+}
+/** `permission(access, …)`, with `access` bound. */
+export type BoundPermission<C extends ModelConfig> = <const T extends ObjectTypeOf<C>, const P extends CheckableOf<C, T>, O extends ObjectData<C, T>>(permission: P, type: T, load: (c: Context) => Awaitable<O | null>, ...options: OptionsArgs<C, T, P, O>) => MiddlewareHandler<{
+    Variables: {
+        object: O;
+    };
+}>;
+/** The functions of this package that take `auth`, with `auth` bound. */
+export interface BoundAuth<A> {
+    readonly session: BoundSession<A>;
+    /** `sendSession(c, auth, signedIn)`: sets the cookie, answers the user. */
+    readonly sendSession: <U>(c: Context, signedIn: {
+        readonly token: string;
+        readonly session: Session;
+        readonly user: U;
+    }) => U;
+    /** `signOut(c, auth)`. */
+    readonly signOut: (c: Context) => Promise<boolean>;
+}
+/** What `bindJanus()` takes: the `janus()` instance, the `permissions()` one, or both. */
+export interface Bindable {
+    readonly auth?: Auth<{
+        readonly type: string;
+    }>;
+    /** What `permission()` takes: a `permissions()` instance, or its `can`. */
+    readonly access?: {
+        readonly can: unknown;
+    };
+}
+/**
+ * What `bindJanus(instances)` answers: `provide()` always; `session`,
+ * `sendSession` and `signOut` with `auth`; `permission` with `access`.
+ */
+export type Bound<I extends Bindable> = {
+    /** `provide(instances)`: every instance bound, on the context. */
+    readonly provide: () => MiddlewareHandler<{
+        Variables: {
+            [K in keyof I & keyof Bindable]: I[K];
+        };
+    }>;
+} & (I['auth'] extends Auth<{
+    readonly type: string;
+}> ? BoundAuth<I['auth']> : unknown) & (I['access'] extends Pick<Permissions<infer C>, 'can'> ? {
+    readonly permission: BoundPermission<C>;
+} : unknown);
+/**
+ * This package's functions with the instances bound once, so no route
+ * repeats them:
+ *
+ * ```ts
+ * const j = bindJanus({ auth, access });
+ * const app = new Hono()
+ *   .use(j.session(), j.provide())
+ *   .get('/records/:id', j.permission('view', 'record', recordOf), (c) => c.json(c.var.object));
+ * ```
+ *
+ * The same functions, typed the same way: `j.session({ required: true })` is
+ * `session(auth, { required: true })`. Only what is given is bound — a
+ * `permission` without `access` is absent from the type.
+ */
+export declare function bindJanus<const I extends Bindable>(instances: I): Bound<I>;
+//# sourceMappingURL=bind.d.ts.map

package/dist/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACX,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,EACN,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,cAAc,EAInB,KAAK,UAAU,EACf,MAAM,WAAW,CAAC;AAEnB,0EAA0E;AAC1E,MAAM,WAAW,YAAY,CAAC,CAAC;IAC9B,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAC7D,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,GACtD,iBAAiB,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAC7D,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;KAAE,GACzD,iBAAiB,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAC7D,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,iBAAiB,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACvC;AAED,oDAAoD;AACpD,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,WAAW,IAAI,CACpD,KAAK,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAC/B,KAAK,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EACjC,CAAC,SAAS,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAE1B,UAAU,EAAE,CAAC,EACb,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EACzC,GAAG,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC/B,iBAAiB,CAAC;IAEtB,SAAS,EAAE;QAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;CACzB,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,WAAW,SAAS,CAAC,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EACvB,CAAC,EAAE,OAAO,EACV,QAAQ,EAAE;QACT,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;KACjB,KACG,CAAC,CAAC;IACP,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACnD;AAED,0FAA0F;AAC1F,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,QAAQ,IAAI;IACvC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,iBAAiB,CAAC;QAEzC,SAAS,EAAE;aAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;SAAE,CAAC;KACrD,CAAC,CAAC;CACH,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GACpB,OAAO,CAAC,GACV,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GACnD;IAAE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;CAAE,GAC3C,OAAO,CAAC,CAAC;AAEb;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,SAAS,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAsB1E"}

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+import { JanusError, type JanusErrorCode } from '@nxgt/janus';
+import type { Context, ErrorHandler } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+/**
+ * The status each code deserves. Exhaustive: a code added to `@nxgt/janus`
+ * stops this file compiling instead of answering `undefined`.
+ *
+ * `STORE_FAILED` is 503 and nothing else — **an outage is not a negative
+ * answer**, and a 401 or a 404 would tell every user they do not exist.
+ */
+export declare function statusOf(code: JanusErrorCode): ContentfulStatusCode;
+/**
+ * The body a refusal is answered with: its `code`, and only what the client
+ * can act on — the fields that failed the schema, the policy's minimum. Never
+ * `reason`, `login`, a hash prefix or a cause: those are for your logs.
+ */
+export declare function bodyOf(error: JanusError): {
+    readonly code: JanusErrorCode;
+    readonly issues?: JanusError['issues'];
+    readonly minLength?: number;
+};
+/** What `janusErrors()` takes. */
+export interface JanusErrorsOptions {
+    /**
+     * Called with every `JanusError` answered 5xx — `STORE_FAILED`,
+     * `UNSUPPORTED`, `PERMISSION_DEPTH`: the ones the server must fix, not the
+     * client — before it is answered. Its `slot`, `operation`, `reason` and
+     * `cause` are for your logs; the body never carries them.
+     *
+     * **It cannot stop the answer**: one that throws, or rejects, is a
+     * `process.emitWarning`, and the 503 is sent all the same.
+     */
+    readonly report?: (error: JanusError, c: Context) => unknown;
+    /** Every error that is not a `JanusError`. Hono's own handling when absent. */
+    readonly fallback?: ErrorHandler;
+}
+/**
+ * An `app.onError` handler: every `JanusError` answered with its status and
+ * `bodyOf(error)`; anything else handed to `fallback` — Hono's own behaviour
+ * when absent.
+ *
+ * Works for either side of `@nxgt/janus`: `can()`'s `STORE_FAILED` is a 503
+ * here too, never a 403.
+ *
+ * ```ts
+ * app.onError(janusErrors({ report: (error) => logger.error(error) }));
+ * ```
+ */
+export declare function janusErrors(options?: JanusErrorsOptions): ErrorHandler;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAElD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CA2BnE;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG;IAC1C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B,CAWA;AAgBD,kCAAkC;AAClC,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7D,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,YAAY,CAQ1E"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@nxgt/janus-hono` — `@nxgt/janus` in a Hono app.
+ *
+ * - `session(auth, options?)` — middleware: `c.var.user` and `c.var.session`
+ *   on every request, a 401 where a user is required, the renewed cookie sent
+ *   again;
+ * - `sendSession(c, auth, signedIn)` and `signOut(c, auth)` — the cookie, set
+ *   and cleared; `sendSession` answers the user;
+ * - `permission(access, permission, type, load)` — middleware: the route runs
+ *   only if the subject holds the permission on the object `load` answers,
+ *   and gets that object as `c.var.object`; `byParam(name, find)` is a `load`
+ *   reading one path parameter;
+ * - `provide({ auth, access })` — the instances on the context, for a route
+ *   that writes users or tuples;
+ * - `janusErrors({ report?, fallback? })` — `app.onError`: every `JanusError`
+ *   as its status, `STORE_FAILED` as 503 and never as 401 or 403; `report`
+ *   sees the 5xx ones first.
+ *
+ * - `bindJanus({ auth, access })` — the functions above with the instances
+ *   bound once: `j.session()`, `j.permission('view', 'record', load)`, …
+ *
+ * It defines no error class: what it lets through is `@nxgt/janus`'s own.
+ */
+export { type Bindable, type Bound, type BoundAuth, type BoundPermission, type BoundSession, bindJanus, } from './bind';
+export { bodyOf, type JanusErrorsOptions, janusErrors, statusOf, } from './errors';
+export { byParam, type ObjectData, type PermissionOptions, permission, } from './permission';
+export { type Instances, provide } from './provide';
+export { type SessionEnv, type SessionOptions, sendSession, session, signOut, type UserOfAuth, } from './session';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,SAAS,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EACN,MAAM,EACN,KAAK,kBAAkB,EACvB,WAAW,EACX,QAAQ,GACR,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,OAAO,EACP,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,UAAU,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACN,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,WAAW,EACX,OAAO,EACP,OAAO,EACP,KAAK,UAAU,GACf,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,181 @@
+// src/permission.ts
+function permission(access, permission, type, load, options = {}) {
+  const can = access.can;
+  return async (c, next) => {
+    if (c.get("object") !== undefined) {
+      throw new TypeError("permission(): c.var.object is already set — one permission() per route; check a parent object through an arrow in the model");
+    }
+    const subject = options.subject === undefined ? userOf(c) : await options.subject(c);
+    if (subject === null || subject === undefined)
+      return c.body(null, 401);
+    const object = await load(c);
+    if (object === null)
+      return c.body(null, 404);
+    const allowed = await can(subject, permission, view(object, type), options.ctx === undefined ? undefined : { ctx: await options.ctx(c, object) });
+    if (!allowed)
+      return c.body(null, 403);
+    c.set("object", object);
+    await next();
+  };
+}
+function byParam(name, find) {
+  return (c) => {
+    const id = c.req.param(name);
+    return id === undefined ? null : find(id);
+  };
+}
+function view(object, type) {
+  return new Proxy(object, {
+    get: (target, key) => key === "type" ? type : Reflect.get(target, key),
+    has: (target, key) => key === "type" || Reflect.has(target, key)
+  });
+}
+function userOf(c) {
+  const user = c.get("user");
+  if (user === undefined) {
+    throw new TypeError("permission(): c.var.user is not set — put session(auth) before it, or pass { subject }");
+  }
+  return user;
+}
+
+// src/provide.ts
+function provide(instances) {
+  return async (c, next) => {
+    if (instances.auth !== undefined)
+      c.set("auth", instances.auth);
+    if (instances.access !== undefined)
+      c.set("access", instances.access);
+    await next();
+  };
+}
+
+// src/session.ts
+import { getCookie } from "hono/cookie";
+function session(auth, options = {}) {
+  return async (c, next) => {
+    const current = await auth.authenticate(c.req.raw, options.type === undefined ? undefined : { type: options.type });
+    if (current === null && options.required === true) {
+      return c.body(null, 401);
+    }
+    c.set("user", current?.user ?? null);
+    c.set("session", current?.session ?? null);
+    await next();
+    const name = `${auth.cookie.name}=`;
+    if (current?.renewed === true && getCookie(c, auth.cookie.name) === current.token && !c.res.headers.getSetCookie().some((value) => value.startsWith(name))) {
+      sendSession(c, auth, current);
+    }
+  };
+}
+function sendSession(c, auth, signedIn) {
+  c.header("Set-Cookie", auth.cookie.serialize(signedIn.token, signedIn.session), {
+    append: true
+  });
+  return signedIn.user;
+}
+async function signOut(c, auth) {
+  const revoked = await auth.signOut(c.req.raw);
+  c.header("Set-Cookie", auth.cookie.clear(), { append: true });
+  return revoked;
+}
+
+// src/bind.ts
+function bindJanus(instances) {
+  const { auth, access } = instances;
+  const bound = {
+    provide: () => provide(instances)
+  };
+  if (auth !== undefined) {
+    bound.session = (options = {}) => session(auth, options);
+    bound.sendSession = (c, signedIn) => sendSession(c, auth, signedIn);
+    bound.signOut = (c) => signOut(c, auth);
+  }
+  if (access !== undefined) {
+    const guard = permission;
+    bound.permission = (...rest) => guard(access, ...rest);
+  }
+  return bound;
+}
+// src/errors.ts
+import { JanusError } from "@nxgt/janus";
+function statusOf(code) {
+  switch (code) {
+    case "STORE_FAILED":
+      return 503;
+    case "NOT_FOUND":
+      return 404;
+    case "LOGIN_TAKEN":
+    case "VERSION_CONFLICT":
+      return 409;
+    case "USER_INVALID":
+    case "PASSWORD_TOO_SHORT":
+    case "HASH_UNSUPPORTED":
+    case "INVALID_CURSOR":
+    case "TOKEN_UNKNOWN":
+    case "TOKEN_SPENT":
+    case "TOKEN_EXPIRED":
+    case "TOKEN_STALE":
+      return 400;
+    case "CREDENTIALS_INVALID":
+      return 401;
+    case "USER_INACTIVE":
+      return 403;
+    case "UNSUPPORTED":
+      return 501;
+    case "PERMISSION_DEPTH":
+      return 500;
+  }
+}
+function bodyOf(error) {
+  switch (error.code) {
+    case "USER_INVALID":
+      return { code: error.code, issues: error.issues ?? [] };
+    case "PASSWORD_TOO_SHORT":
+      return error.minLength === undefined ? { code: error.code } : { code: error.code, minLength: error.minLength };
+    default:
+      return { code: error.code };
+  }
+}
+function honoDefault(error, c) {
+  if ("getResponse" in error) {
+    const response = error.getResponse();
+    return c.newResponse(response.body, response);
+  }
+  console.error(error);
+  return c.text("Internal Server Error", 500);
+}
+function janusErrors(options = {}) {
+  const { report, fallback = honoDefault } = options;
+  return (error, c) => {
+    if (!(error instanceof JanusError))
+      return fallback(error, c);
+    const status = statusOf(error.code);
+    if (status >= 500 && report !== undefined)
+      reportSafely(report, error, c);
+    return c.json(bodyOf(error), status);
+  };
+}
+function reportSafely(report, error, c) {
+  const warn = (failure) => process.emitWarning(`janusErrors: report failed on ${error.code}: ${failure instanceof Error ? failure.name : typeof failure}`);
+  try {
+    const reported = report(error, c);
+    if (reported instanceof Promise)
+      reported.then(undefined, warn);
+  } catch (failure) {
+    warn(failure);
+  }
+}
+export {
+  bindJanus,
+  bodyOf,
+  byParam,
+  janusErrors,
+  permission,
+  provide,
+  sendSession,
+  session,
+  signOut,
+  statusOf
+};
+
+//# debugId=93D6634A3905348664756E2164756E21
+//# sourceMappingURL=index.js.map