@softistx/janus-hono 0.0.0-stage → 0.11.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +547 -2
- package/dist/bind.d.ts +104 -0
- package/dist/bind.d.ts.map +1 -0
- package/dist/device.d.ts +15 -0
- package/dist/device.d.ts.map +1 -0
- package/dist/errors.d.ts +60 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/fresh.d.ts +41 -0
- package/dist/fresh.d.ts.map +1 -0
- package/dist/index.d.ts +47 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +496 -0
- package/dist/index.js.map +22 -0
- package/dist/no-store.d.ts +8 -0
- package/dist/no-store.d.ts.map +1 -0
- package/dist/passkeys/body.d.ts +12 -0
- package/dist/passkeys/body.d.ts.map +1 -0
- package/dist/passkeys/index.d.ts +8 -0
- package/dist/passkeys/index.d.ts.map +1 -0
- package/dist/passkeys/routes.d.ts +32 -0
- package/dist/passkeys/routes.d.ts.map +1 -0
- package/dist/passkeys/types.d.ts +105 -0
- package/dist/passkeys/types.d.ts.map +1 -0
- package/dist/permission.d.ts +80 -0
- package/dist/permission.d.ts.map +1 -0
- package/dist/provide.d.ts +19 -0
- package/dist/provide.d.ts.map +1 -0
- package/dist/session.d.ts +156 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/social/index.d.ts +9 -0
- package/dist/social/index.d.ts.map +1 -0
- package/dist/social/redirect.d.ts +9 -0
- package/dist/social/redirect.d.ts.map +1 -0
- package/dist/social/refusals.d.ts +14 -0
- package/dist/social/refusals.d.ts.map +1 -0
- package/dist/social/routes.d.ts +32 -0
- package/dist/social/routes.d.ts.map +1 -0
- package/dist/social/types.d.ts +90 -0
- package/dist/social/types.d.ts.map +1 -0
- package/docs/README.md +15 -0
- package/docs/guide/permissions.md +225 -0
- package/docs/guide/routes.md +1164 -0
- package/docs/roadmap.md +76 -0
- package/docs/troubleshooting.md +871 -0
- package/package.json +62 -5
package/dist/bind.d.ts
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import type { Session } from '@softistx/janus';
|
|
2
|
+
import type { CheckableOf, ModelConfig, ObjectTypeOf, Permissions } from '@softistx/janus/permissions';
|
|
3
|
+
import type { Context, Hono, MiddlewareHandler } from 'hono';
|
|
4
|
+
import { type PasskeyRoutesOptions, type PasskeyTypeApi, type PasskeyTypeNames } from './passkeys';
|
|
5
|
+
import { type Awaitable, type ObjectData, type OptionsArgs } from './permission';
|
|
6
|
+
import { type Auth, type PrincipalEnv, type SendSessionOptions, type SessionEnv, type SessionOptions, type UserOfAuth } from './session';
|
|
7
|
+
import { type SocialAuth, type SocialRoutesOptions } from './social';
|
|
8
|
+
/** `session(auth, options?)`, with `auth` bound: the same three forms. */
|
|
9
|
+
export interface BoundSession<A> {
|
|
10
|
+
<const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: SessionOptions<T> & {
|
|
11
|
+
readonly required: true;
|
|
12
|
+
readonly apiKey: true;
|
|
13
|
+
}): MiddlewareHandler<PrincipalEnv<A, T, true>>;
|
|
14
|
+
<const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: SessionOptions<T> & {
|
|
15
|
+
readonly apiKey: true;
|
|
16
|
+
}): MiddlewareHandler<PrincipalEnv<A, T>>;
|
|
17
|
+
<const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: SessionOptions<T> & {
|
|
18
|
+
readonly required: true;
|
|
19
|
+
readonly apiKey?: false;
|
|
20
|
+
}): MiddlewareHandler<SessionEnv<A, T, true>>;
|
|
21
|
+
<const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options?: SessionOptions<T> & {
|
|
22
|
+
readonly required?: false;
|
|
23
|
+
readonly apiKey?: false;
|
|
24
|
+
}): MiddlewareHandler<SessionEnv<A, T>>;
|
|
25
|
+
<const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(options: SessionOptions<T>): MiddlewareHandler<SessionEnv<A, T>>;
|
|
26
|
+
}
|
|
27
|
+
/** `permission(access, …)`, with `access` bound. */
|
|
28
|
+
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<{
|
|
29
|
+
Variables: {
|
|
30
|
+
object: O;
|
|
31
|
+
};
|
|
32
|
+
}>;
|
|
33
|
+
/** The functions of this package that take `auth`, with `auth` bound. */
|
|
34
|
+
export interface BoundAuth<A> {
|
|
35
|
+
readonly session: BoundSession<A>;
|
|
36
|
+
/** `sendSession(c, auth, signedIn, options?)`: sets the cookies, answers the user. */
|
|
37
|
+
readonly sendSession: <U>(c: Context, signedIn: {
|
|
38
|
+
readonly token: string;
|
|
39
|
+
readonly session: Session;
|
|
40
|
+
readonly user: U;
|
|
41
|
+
readonly deviceToken?: string | null;
|
|
42
|
+
}, options?: SendSessionOptions) => U;
|
|
43
|
+
/** `signOut(c, auth)`. */
|
|
44
|
+
readonly signOut: (c: Context) => Promise<boolean>;
|
|
45
|
+
}
|
|
46
|
+
/** `socialRoutes(auth, options)`, with `auth` bound: present when `auth` configures `social`. */
|
|
47
|
+
export interface BoundSocial<A extends SocialAuth> {
|
|
48
|
+
readonly socialRoutes: (options: SocialRoutesOptions<A>) => Hono;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* `passkeyRoutes(auth, options?)`, with `auth` bound: present when `auth`
|
|
52
|
+
* configures `passkeys`. With several user types the `type` is required and
|
|
53
|
+
* names one that does.
|
|
54
|
+
*/
|
|
55
|
+
export type BoundPasskeys<A> = A extends PasskeyTypeApi ? {
|
|
56
|
+
readonly passkeyRoutes: (options?: PasskeyRoutesOptions) => Hono;
|
|
57
|
+
} : [PasskeyTypeNames<A>] extends [never] ? unknown : {
|
|
58
|
+
readonly passkeyRoutes: <const T extends PasskeyTypeNames<A>>(options: PasskeyRoutesOptions<T> & {
|
|
59
|
+
readonly type: T;
|
|
60
|
+
}) => Hono;
|
|
61
|
+
};
|
|
62
|
+
/** What `bindJanus()` takes: the `janus()` instance, the `permissions()` one, or both. */
|
|
63
|
+
export interface Bindable {
|
|
64
|
+
readonly auth?: Auth<{
|
|
65
|
+
readonly type: string;
|
|
66
|
+
}>;
|
|
67
|
+
/** What `permission()` takes: a `permissions()` instance, or its `can`. */
|
|
68
|
+
readonly access?: {
|
|
69
|
+
readonly can: unknown;
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* What `bindJanus(instances)` answers: `provide()` always; `session`,
|
|
74
|
+
* `sendSession` and `signOut` with `auth`, `socialRoutes` when it configures `social`, `passkeyRoutes` when it configures `passkeys`; `permission` with `access`.
|
|
75
|
+
*/
|
|
76
|
+
export type Bound<I extends Bindable> = {
|
|
77
|
+
/** `provide(instances)`: every instance bound, on the context. */
|
|
78
|
+
readonly provide: () => MiddlewareHandler<{
|
|
79
|
+
Variables: {
|
|
80
|
+
[K in keyof I & keyof Bindable]: I[K];
|
|
81
|
+
};
|
|
82
|
+
}>;
|
|
83
|
+
} & (I['auth'] extends Auth<{
|
|
84
|
+
readonly type: string;
|
|
85
|
+
}> ? BoundAuth<I['auth']> & (I['auth'] extends SocialAuth ? BoundSocial<I['auth']> : unknown) & BoundPasskeys<I['auth']> : unknown) & (I['access'] extends Pick<Permissions<infer C>, 'can'> ? {
|
|
86
|
+
readonly permission: BoundPermission<C>;
|
|
87
|
+
} : unknown);
|
|
88
|
+
/**
|
|
89
|
+
* This package's functions with the instances bound once, so no route
|
|
90
|
+
* repeats them:
|
|
91
|
+
*
|
|
92
|
+
* ```ts
|
|
93
|
+
* const j = bindJanus({ auth, access });
|
|
94
|
+
* const app = new Hono()
|
|
95
|
+
* .use(j.session(), j.provide())
|
|
96
|
+
* .get('/records/:id', j.permission('view', 'record', recordOf), (c) => c.json(c.var.object));
|
|
97
|
+
* ```
|
|
98
|
+
*
|
|
99
|
+
* The same functions, typed the same way: `j.session({ required: true })` is
|
|
100
|
+
* `session(auth, { required: true })`. Only what is given is bound — a
|
|
101
|
+
* `permission` without `access` is absent from the type.
|
|
102
|
+
*/
|
|
103
|
+
export declare function bindJanus<const I extends Bindable>(instances: I): Bound<I>;
|
|
104
|
+
//# sourceMappingURL=bind.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"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"}
|
package/dist/device.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { DEVICE_COOKIE, type DeviceCookieOptions } from '@softistx/janus';
|
|
2
|
+
import type { Context } from 'hono';
|
|
3
|
+
export { DEVICE_COOKIE, type DeviceCookieOptions };
|
|
4
|
+
/**
|
|
5
|
+
* The device token the request's cookie holds, or `null` when it holds none:
|
|
6
|
+
* what a sign-in takes as `device`.
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* const signedIn = await auth.signIn({ email, password }, { device: deviceOf(c) });
|
|
10
|
+
* ```
|
|
11
|
+
*/
|
|
12
|
+
export declare function deviceOf(c: Context, options?: DeviceCookieOptions): string | null;
|
|
13
|
+
/** Sets the device cookie, or sets it again so it lasts another `maxAge`. Appends. */
|
|
14
|
+
export declare function sendDevice(c: Context, deviceToken: string, options?: DeviceCookieOptions): void;
|
|
15
|
+
//# sourceMappingURL=device.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EACb,KAAK,mBAAmB,EAGxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACvB,CAAC,EAAE,OAAO,EACV,OAAO,GAAE,mBAAwB,GAC/B,MAAM,GAAG,IAAI,CAEf;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CACzB,CAAC,EAAE,OAAO,EACV,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAC/B,IAAI,CAEN"}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { JanusError, type JanusErrorCode } from '@softistx/janus';
|
|
2
|
+
import type { Context, ErrorHandler } from 'hono';
|
|
3
|
+
import type { ContentfulStatusCode } from 'hono/utils/http-status';
|
|
4
|
+
/**
|
|
5
|
+
* The status each code deserves: `@softistx/janus`'s own table, typed as the
|
|
6
|
+
* `ContentfulStatusCode` `c.json()` takes. Kept as an export of its own so a
|
|
7
|
+
* route that answers by hand reads the same status `janusErrors()` does.
|
|
8
|
+
*
|
|
9
|
+
* `STORE_FAILED` is 503 and nothing else — **an outage is not a negative
|
|
10
|
+
* answer**, and a 401 or a 404 would tell every user they do not exist.
|
|
11
|
+
*/
|
|
12
|
+
export declare function statusOf(code: JanusErrorCode): ContentfulStatusCode;
|
|
13
|
+
/**
|
|
14
|
+
* The body a refusal is answered with: its `code`, and only what the client
|
|
15
|
+
* can act on — the fields that failed the schema, the policy's minimum, the
|
|
16
|
+
* attempts a challenge has left, the key or passkey limit a user hit, the field of an API key or a passkey's name that was refused, the seconds a throttled sign-in, a
|
|
17
|
+
* throttled request for an e-mail or an app's code past the user's window waits.
|
|
18
|
+
* Never `reason` (an invitation code's refusal reason is GraphQL's alone for now), `login`, a hash prefix or a cause: those are for your logs.
|
|
19
|
+
*/
|
|
20
|
+
export declare function bodyOf(error: JanusError): {
|
|
21
|
+
readonly code: JanusErrorCode;
|
|
22
|
+
readonly issues?: JanusError['issues'];
|
|
23
|
+
readonly minLength?: number;
|
|
24
|
+
readonly attemptsLeft?: number;
|
|
25
|
+
readonly retryAfter?: number;
|
|
26
|
+
readonly maxActive?: number;
|
|
27
|
+
readonly field?: JanusError['field'];
|
|
28
|
+
};
|
|
29
|
+
/** What `janusErrors()` takes. */
|
|
30
|
+
export interface JanusErrorsOptions {
|
|
31
|
+
/**
|
|
32
|
+
* Called with every `JanusError` answered 5xx — `STORE_FAILED`,
|
|
33
|
+
* `UNSUPPORTED`, `PERMISSION_DEPTH`: the ones the server must fix, not the
|
|
34
|
+
* client — before it is answered. Its `slot`, `operation`, `reason` and
|
|
35
|
+
* `cause` are for your logs; the body never carries them.
|
|
36
|
+
*
|
|
37
|
+
* **It cannot stop the answer**: one that throws, or rejects, is a
|
|
38
|
+
* `process.emitWarning`, and the 503 is sent all the same.
|
|
39
|
+
*/
|
|
40
|
+
readonly report?: (error: JanusError, c: Context) => unknown;
|
|
41
|
+
/** Every error that is not a `JanusError`. Hono's own handling when absent. */
|
|
42
|
+
readonly fallback?: ErrorHandler;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* An `app.onError` handler: every `JanusError` answered with its status and
|
|
46
|
+
* `bodyOf(error)` — and a throttled sign-in, or a request past its e-mails
|
|
47
|
+
* (`MAIL_THROTTLED`, 429) or an app's code past the user's window
|
|
48
|
+
* (`CODE_INVALID`, 401), with a `Retry-After` header, its `retryAfter` in
|
|
49
|
+
* seconds; anything else handed to `fallback` — Hono's own
|
|
50
|
+
* behaviour when absent.
|
|
51
|
+
*
|
|
52
|
+
* Works for either side of `@softistx/janus`: `can()`'s `STORE_FAILED` is a 503
|
|
53
|
+
* here too, never a 403.
|
|
54
|
+
*
|
|
55
|
+
* ```ts
|
|
56
|
+
* app.onError(janusErrors({ report: (error) => logger.error(error) }));
|
|
57
|
+
* ```
|
|
58
|
+
*/
|
|
59
|
+
export declare function janusErrors(options?: JanusErrorsOptions): ErrorHandler;
|
|
60
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,UAAU,EACV,KAAK,cAAc,EAEnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAElD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAEnE;AAED;;;;;;GAMG;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;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CACrC,CAsCA;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;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,YAAY,CAY1E"}
|
package/dist/fresh.d.ts
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { type Clock, type Duration, type Principal, type Session } from '@softistx/janus';
|
|
2
|
+
import type { MiddlewareHandler } from 'hono';
|
|
3
|
+
/** What `fresh()` takes besides `maxAge`. */
|
|
4
|
+
export interface FreshOptions {
|
|
5
|
+
/** The clock given to `janus()`, when it is not the system's: `fixedClock` in a spec. */
|
|
6
|
+
readonly clock?: Clock;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* The middleware that lets a route run only for a session that proved who
|
|
10
|
+
* it is less than `maxAge` ago — signed in, or confirmed by
|
|
11
|
+
* `auth.stepUp.confirm`, since. Behind `session(auth)`, which sets
|
|
12
|
+
* `c.var.session`:
|
|
13
|
+
*
|
|
14
|
+
* ```ts
|
|
15
|
+
* app.delete('/account', session(auth, { required: true }), fresh('10m'), deleteAccount);
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
18
|
+
* A session older than that throws `STEP_UP_REQUIRED`, which `janusErrors()`
|
|
19
|
+
* answers 403 with `{ code: 'STEP_UP_REQUIRED' }`: the client asks for a
|
|
20
|
+
* step-up, then sends the request again. An anonymous request is answered
|
|
21
|
+
* 401, with no body, as `session(auth, { required: true })` answers it.
|
|
22
|
+
*
|
|
23
|
+
* **A key is never fresh**: behind `session(auth, { apiKey: true })`, a
|
|
24
|
+
* request that presented an API key throws `STEP_UP_REQUIRED` with
|
|
25
|
+
* `reason: 'apiKey'` (a 403 `{ code: 'STEP_UP_REQUIRED' }`) — a step-up cannot
|
|
26
|
+
* make a key fresh, so the client must use a signed-in session.
|
|
27
|
+
*
|
|
28
|
+
* A `maxAge` that is not a duration is a `TypeError` here, when the app is
|
|
29
|
+
* wired — not on the first request.
|
|
30
|
+
* No `session()` before it is a `TypeError` at the first request — a
|
|
31
|
+
* wiring error, not an anonymous 401 — as for `permission()`.
|
|
32
|
+
*/
|
|
33
|
+
export declare function fresh(maxAge: Duration, options?: FreshOptions): MiddlewareHandler<{
|
|
34
|
+
Variables: {
|
|
35
|
+
session: Session | null;
|
|
36
|
+
principal?: Principal<{
|
|
37
|
+
readonly id: string;
|
|
38
|
+
}> | null;
|
|
39
|
+
};
|
|
40
|
+
}>;
|
|
41
|
+
//# sourceMappingURL=fresh.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fresh.d.ts","sourceRoot":"","sources":["../src/fresh.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,KAAK,EACV,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,OAAO,EAGZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CACpB,MAAM,EAAE,QAAQ,EAChB,OAAO,GAAE,YAAiB,GACxB,iBAAiB,CAAC;IAEpB,SAAS,EAAE;QACV,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,EAAE,SAAS,CAAC;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,GAAG,IAAI,CAAC;KACtD,CAAC;CACF,CAAC,CA4BD"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@softistx/janus-hono` — `@softistx/janus` in a Hono app.
|
|
3
|
+
*
|
|
4
|
+
* - `session(auth, options?)` — middleware: `c.var.user` and `c.var.session`
|
|
5
|
+
* on every request, a 401 where a user is required, the renewed cookie sent
|
|
6
|
+
* again;
|
|
7
|
+
* - `session(auth, { apiKey: true })` also accepts an API key: `c.var.principal`
|
|
8
|
+
* and `c.var.apiKey` say which one it was;
|
|
9
|
+
* - `fresh(maxAge, options?)` — middleware, behind `session(auth)`: the
|
|
10
|
+
* route runs only for a session that proved who it is less than `maxAge`
|
|
11
|
+
* ago, `STEP_UP_REQUIRED` otherwise (always, for an API key);
|
|
12
|
+
* - `sendSession(c, auth, signedIn, options?)` and `signOut(c, auth)` — the
|
|
13
|
+
* cookie, set and cleared; `sendSession` answers the user, and sets the
|
|
14
|
+
* device cookie when the sign-in answered a `deviceToken`;
|
|
15
|
+
* - `deviceOf(c, options?)` — the device token the request's cookie holds,
|
|
16
|
+
* or `null`: what a sign-in takes as `device`;
|
|
17
|
+
* - `permission(access, permission, type, load)` — middleware: the route runs
|
|
18
|
+
* only if the subject holds the permission on the object `load` answers,
|
|
19
|
+
* and gets that object as `c.var.object`; `byParam(name, find)` is a `load`
|
|
20
|
+
* reading one path parameter;
|
|
21
|
+
* - `socialRoutes(auth, { onSecondFactor, … })` — a sub-app: sign in, sign up
|
|
22
|
+
* and link accounts through an external provider (redirect, callback,
|
|
23
|
+
* unlink), refusals as `?socialError=<code>` redirects;
|
|
24
|
+
* - `passkeyRoutes(auth, options?)` — a sub-app: register, list, rename and
|
|
25
|
+
* remove passkeys, answer a sign-in's second factor and a step-up with one,
|
|
26
|
+
* all JSON;
|
|
27
|
+
* - `provide({ auth, access })` — the instances on the context, for a route
|
|
28
|
+
* that writes users or tuples;
|
|
29
|
+
* - `janusErrors({ report?, fallback? })` — `app.onError`: every `JanusError`
|
|
30
|
+
* as its status, `STORE_FAILED` as 503 and never as 401 or 403; `report`
|
|
31
|
+
* sees the 5xx ones first.
|
|
32
|
+
*
|
|
33
|
+
* - `bindJanus({ auth, access })` — the functions above with the instances
|
|
34
|
+
* bound once: `j.session()`, `j.permission('view', 'record', load)`, …
|
|
35
|
+
*
|
|
36
|
+
* It defines no error class: what it lets through is `@softistx/janus`'s own.
|
|
37
|
+
*/
|
|
38
|
+
export { type Bindable, type Bound, type BoundAuth, type BoundPasskeys, type BoundPermission, type BoundSession, type BoundSocial, bindJanus, } from './bind';
|
|
39
|
+
export { DEVICE_COOKIE, type DeviceCookieOptions, deviceOf } from './device';
|
|
40
|
+
export { bodyOf, type JanusErrorsOptions, janusErrors, statusOf, } from './errors';
|
|
41
|
+
export { type FreshOptions, fresh } from './fresh';
|
|
42
|
+
export { type PasskeyAuth, type PasskeyRoutesOptions, type PasskeySurface, type PasskeysSurface, type PasskeyTypeApi, type PasskeyTypeNames, passkeyRoutes, type StepUpPasskeySurface, } from './passkeys';
|
|
43
|
+
export { byParam, type ObjectData, type PermissionOptions, permission, } from './permission';
|
|
44
|
+
export { type Instances, provide } from './provide';
|
|
45
|
+
export { type PrincipalEnv, type SendSessionOptions, type SessionEnv, type SessionOptions, sendSession, session, signOut, type UserOfAuth, } from './session';
|
|
46
|
+
export { type SecondFactorOf, type SocialAuth, type SocialRoutesOptions, type SocialSurface, socialRoutes, } from './social';
|
|
47
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,SAAS,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,EACN,MAAM,EACN,KAAK,kBAAkB,EACvB,WAAW,EACX,QAAQ,GACR,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,aAAa,EACb,KAAK,oBAAoB,GACzB,MAAM,YAAY,CAAC;AACpB,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,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,WAAW,EACX,OAAO,EACP,OAAO,EACP,KAAK,UAAU,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,YAAY,GACZ,MAAM,UAAU,CAAC"}
|