@elysiumjs/themis 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# @elysiumjs/themis
+
+## 0.1.0
+
+### Minor Changes
+
+- [#19](https://github.com/na2axl/elysiumjs/pull/19) [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562) Thanks [@na2axl](https://github.com/na2axl)! - Domain errors as classes with a code, returned as values.
+
+  - `DomainError` is an Elysia `HTTPError`. Each error is a class made with `DomainError.for(code, status)`, which keeps its code and status as literal types, with `errors`, `retryAfterSeconds` (served as `retryAfter` and the Retry-After header) and extensions.
+  - Ready-made errors: `BadRequestError`, `ValidationFailedError`, `UnauthenticatedError`, `ForbiddenError`, `NotFoundError` and `ConflictError`.
+  - `ProblemCatalogue`, extended through declaration merging, lists the codes of an application; once it has keys, `DomainError.for()` takes only those and `ELYSIUM_PROBLEM_CODES`.
+  - Every problem carries `code`, `requestId` (from `problems.requestId`, a valid `x-request-id` header, or a random UUID) and `instance`. Its `type` is the kebab-case slug of the code, under `problems.typeBase`.
+  - Errors as values: a handler, a flow step, `UnitOfWork.run()` or a `@Transactional()` method that returns a DomainError rolls back and sends or returns it like a thrown one. `Commands.execute()` and `Queries.ask()` return the DomainError that refused the call, and a returned error joins the route's response type for typed clients.
+
+- [#17](https://github.com/na2axl/elysiumjs/pull/17) [`03e062d`](https://github.com/na2axl/elysiumjs/commit/03e062d9f5d8ec761c63f05574ce96a1084fe3ea) Thanks [@na2axl](https://github.com/na2axl)! - Commands, outbox, authentication and multi-step flows, on Bun, Node.js and Cloudflare Workers.
+
+  Added:
+
+  - `@elysiumjs/moirai`: commands and queries declared with `@Moirai.command()` and `@Moirai.query()`, run with `Commands.execute` and `Queries.ask`. Inputs are validated (400 problem), `authorize` refuses with a 403 problem, commands run in a unit of work and retry transient failures, idempotent commands replay their response for a repeated key (428 without a key, 422 for a key reused with another input), and `serializeBy` runs calls with the same key one after the other. `Outbox.enqueue` writes effects that relay once the unit of work commits, to `@Moirai.effect()` handlers, with a backoff and dead rows; `Outbox.sweep` relays what is due; `Inbox.once` processes a message once per consumer. `@elysiumjs/moirai/heracles` adds `job()`, an effect that dispatches a Heracles job. Memory stores for tests.
+  - `@elysiumjs/moirai-drizzle`: Postgres stores for moirai through Drizzle ORM: `moiraiTables(schema?)`, `DrizzleIdempotencyStore`, `DrizzleOutboxStore` (claims with `FOR UPDATE SKIP LOCKED`), `DrizzleInboxStore` and `PgAdvisoryLock`.
+  - `@elysiumjs/themis`: password hashing (argon2id on Bun, PBKDF2 everywhere, scrypt on `@elysiumjs/themis/scrypt`), JWT through jose, API keys, signed URLs, sessions (memory, Redis, Workers KV, or an encrypted cookie), `@Auth()` with session, JWT and API key guards (401 problem), picked by name through `AuthMiddleware.guards()` of core middleware, CSRF protection, TOTP and backup codes, OAuth 2.0 and OpenID Connect clients with PKCE through oauth4webapi, and passkeys through SimpleWebAuthn.
+  - `@elysiumjs/ariadne`: multi-step flows as controllers: `@Flow.controller()` adds the start and state routes, each `@Flow.step()` method is a route that takes the `@Http.*()` parameter decorators, and `@Flow.state()` / `@Flow.context()` inject the flow. Replay of a repeated step id, refused steps that keep their state, back steps, guest and user owners, a flow that ends when `next` gives no step, and a memory store set by `AriadneModule.with({ store })`.
+  - `@elysiumjs/ariadne-redis`: `RedisFlowStore`, whose claims and commits are atomic Lua scripts run with `EVAL`, which Upstash runs too.
+  - `@elysiumjs/ariadne-workers`: `FlowStoreObject`, a Durable Object flow store, and `durableFlowStore(binding)`.
+
+### Patch Changes
+
+- Updated dependencies [[`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c), [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148), [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82), [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4), [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562), [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5), [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64), [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df), [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4), [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d), [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4), [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88), [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576), [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b)]:
+  - @elysiumjs/core@0.11.0

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @elysiumjs/themis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Authentication for [Elysium.js](../core) apps: passwords, tokens, sessions, guards, CSRF, TOTP, OAuth/OpenID Connect and passkeys. It runs on Bun, Node.js and Cloudflare Workers.
+
+## Installation
+
+```bash
+bun add @elysiumjs/themis
+# Sessions in Redis or Workers KV
+bun add @elysiumjs/themis-redis   # or @elysiumjs/themis-workers
+```
+
+## Setup
+
+```ts
+import { Application, Middleware } from '@elysiumjs/core';
+import { Redis } from '@elysiumjs/redis';
+import {
+	apiKeyGuard,
+	CsrfMiddleware,
+	jwtGuard,
+	sessionGuard,
+	SessionMiddleware,
+	ThemisModule
+} from '@elysiumjs/themis';
+import { RedisSessionStore } from '@elysiumjs/themis-redis';
+
+@Application.register({
+	modules: [
+		ThemisModule.with({
+			secret: env.APP_SECRET,
+			session: {
+				store: new RedisSessionStore({ connection: () => Redis.connection() }),
+				ttl: 60 * 60 * 24 * 7
+			},
+			guards: {
+				session: sessionGuard({ user: (id) => users.find(id) }),
+				jwt: jwtGuard({ secret: env.JWT_SECRET, user: (claims) => users.find(claims.sub) }),
+				apiKey: apiKeyGuard({ find: (hash) => keys.ownerOf(hash) })
+			}
+		}),
+		AppModule
+	]
+})
+@Middleware.register(SessionMiddleware, CsrfMiddleware)
+class App extends Application {}
+```
+
+`secret` signs the session cookie, encrypts cookie sessions and binds CSRF tokens. Keep it in an environment secret. A secret under 32 bytes is refused at boot (`WeakSecretError`), and so are shorter JWT and signed URL secrets.
+
+## Auth
+
+```ts
+import { Http } from '@elysiumjs/core';
+import { Auth } from '@elysiumjs/themis';
+
+@Http.controller('/me')
+@Auth()
+class MeController {
+	@Http.get()
+	public me() {
+		return Auth.user();
+	}
+
+	@Http.get('/tokens')
+	@Auth({ guards: ['jwt'] })
+	public tokens() {
+		/* ... */
+	}
+}
+```
+
+- `@Auth()` tries the configured guards in order, and `@Auth({ guards })` only the named ones. A guard is an object that implements `Guard`, or a guard class, which is built once through the service container so that its constructor gets services injected. It registers `AuthMiddleware`, so `@Middleware.register(AuthMiddleware.guards(['jwt']))` does the same as `@Auth({ guards: ['jwt'] })`.
+- A request no guard accepts answers a 401 problem. `@Auth({ optional: true })` lets it through, and `Auth.check()` tells whether a user is signed in.
+- The user is available through `Auth.user()` and `ctx.currentUser`, so cerberus can read it with `getSubject: (ctx) => ctx.currentUser`.
+- `Auth.login(id)` signs a user in on the session (and regenerates it), and `Auth.logout()` signs them out.
+
+## Sessions
+
+```ts
+import { Session } from '@elysiumjs/themis';
+
+const session = Session.current();
+session.set('cart', items);
+session.flash('notice', 'Saved');
+session.regenerate();
+```
+
+- The stores are `MemorySessionStore`, `RedisSessionStore` of [`@elysiumjs/themis-redis`](../themis-redis) and `KvSessionStore` of [`@elysiumjs/themis-workers`](../themis-workers) (a Workers KV binding). Without a store, sessions live in the memory of the process, and themis warns about it outside tests.
+- `store: 'cookie'` keeps the whole session in an AES-GCM encrypted cookie. It must stay under 4000 characters (`SessionTooLargeError`), and a copied cookie stays valid until it expires, so keep revocable sessions in a store.
+- The session cookie is signed, `HttpOnly`, `SameSite=Lax` and `Secure` by default.
+- The session is saved after the handler runs, and also when the request ends with a client error (4xx), such as a sign-in followed by a thrown problem.
+
+## CSRF
+
+`CsrfMiddleware` protects cookie sessions with a synchronizer token kept in the session. Unsafe methods need the `x-csrf-token` header or the `_csrf` field to match `Csrf.token()`, or they answer a 403 problem.
+
+## Passwords
+
+```ts
+import { Password } from '@elysiumjs/themis';
+
+const hash = await Password.hash(input);
+if ((await Password.verify(input, hash)) && Password.needsRehash(hash)) {
+	await users.updateHash(id, await Password.hash(input));
+}
+```
+
+The hasher is argon2id (`BunPasswordHasher`) on Bun and PBKDF2-SHA256 (`Pbkdf2PasswordHasher`) elsewhere, with 600,000 iterations (100,000 on Cloudflare Workers, which cap PBKDF2 there). `ScryptPasswordHasher`, from `@elysiumjs/themis/scrypt`, uses `node:crypto`. Pick one with `Password.use(hasher)`. Hashes describe their format, so `verify` reads all three.
+
+## Tokens
+
+```ts
+import { ApiKeys, Jwt, SignedUrl } from '@elysiumjs/themis';
+
+const token = await Jwt.sign({ role: 'admin' }, { secret, subject: user.id, expiresIn: 3600 });
+const claims = await Jwt.verify(token, { secret });
+
+const { key, hash } = await ApiKeys.generate({ prefix: 'sk' }); // store the hash, show the key once
+await ApiKeys.verify(key, hash);
+
+const link = await SignedUrl.sign('https://app.example.com/download/1', { secret, expiresIn: 600 });
+await SignedUrl.verify(link, { secret });
+```
+
+`Jwt` signs with a secret (HS256) or with an asymmetric key and its algorithm. An invalid or expired token is a 401 problem, and an invalid or expired link a 403 problem.
+
+## Two-factor codes
+
+```ts
+import { BackupCodes, Totp } from '@elysiumjs/themis';
+
+const secret = Totp.generateSecret();
+const qr = Totp.uri({ secret, issuer: 'Acme', account: user.email });
+const counter = await Totp.verify(code, secret, { window: 1 }); // null when wrong
+
+const { codes, hashes } = await BackupCodes.generate(10);
+const { valid, remaining } = await BackupCodes.consume(typed, hashes);
+```
+
+Store the counter `Totp.verify` returns and refuse a code whose counter is not greater, so that a code works once.
+
+## OAuth and OpenID Connect
+
+```ts
+import { OAuthClient } from '@elysiumjs/themis';
+
+const google = new OAuthClient({
+	issuer: 'https://accounts.google.com',
+	clientId: env.GOOGLE_CLIENT_ID,
+	clientSecret: env.GOOGLE_CLIENT_SECRET,
+	redirectUri: 'https://api.example.com/auth/google/callback'
+});
+
+// GET /auth/google
+const url = await google.authorize();
+
+// GET /auth/google/callback
+const { tokens, claims, userInfo } = await google.callback(request.url);
+```
+
+The client uses the authorization code flow with PKCE. The state, the verifier and the OpenID Connect nonce are kept in the session. A provider without discovery takes `authorizationServer` with its endpoints. A callback with a wrong state or a failed exchange answers a 400 problem. Its detail names the OAuth error code the provider answered; any other failure is logged and answered with a fixed detail.
+
+## Passkeys
+
+```ts
+import { Passkeys } from '@elysiumjs/themis';
+
+const passkeys = new Passkeys({
+	rpName: 'Acme',
+	rpID: 'example.com',
+	origin: 'https://example.com',
+	repository: new PasskeyTable()
+});
+
+const options = await passkeys.registrationOptions({ id: user.id, name: user.email });
+const record = await passkeys.verifyRegistration(response);
+
+const challenge = await passkeys.authenticationOptions();
+const used = await passkeys.verifyAuthentication(assertion); // used.userId signs the user in
+```
+
+The challenge is kept in the session. The app stores credentials by implementing `PasskeyRepository`. A response that does not verify answers a 400 problem.

package/dist/api-keys.d.ts

@@ -0,0 +1,26 @@
+export declare namespace ApiKeys {
+    /**
+     * Generates an API key: a prefix, then 32 random bytes. Show the key once and store only its
+     * hash.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param options The prefix, which tells the keys apart in logs and secret scanners.
+     * @returns The key, and its hash to store.
+     */
+    const generate: (options?: {
+        prefix?: string;
+    }) => Promise<{
+        key: string;
+        hash: string;
+    }>;
+    /**
+     * The hash of a key, to look the key up: the hex SHA-256. Keys carry enough entropy for an
+     * unsalted hash.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const hash: (key: string) => Promise<string>;
+    /**
+     * Whether a presented key matches a stored hash, compared in constant time.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const verify: (key: string, storedHash: string) => Promise<boolean>;
+}

package/dist/auth.d.ts

@@ -0,0 +1,107 @@
+import type { HttpContext } from './context';
+import type { JwtVerifyOptions } from './jwt';
+import { Middleware } from '@elysiumjs/core';
+/**
+ * Finds the user of a request, or answers `undefined` when the request does not carry what the
+ * guard reads. A guard throws to refuse a request that carries invalid credentials.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface Guard {
+    authenticate(context: HttpContext): Promise<unknown> | unknown;
+}
+/**
+ * A guard class, built once through the service container, so that its constructor gets its
+ * services injected like a middleware or a filter.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @example
+ * ```ts
+ * class DeviceGuard implements Guard {
+ * 	constructor(private readonly devices: DeviceRepository) {}
+ *
+ * 	public async authenticate(context: HttpContext) {
+ * 		const token = context.request.headers.get('x-device-token');
+ * 		return token ? this.devices.ownerOf(token) : undefined;
+ * 	}
+ * }
+ *
+ * ThemisModule.with({ secret, guards: { device: DeviceGuard } });
+ * ```
+ */
+export type GuardClass = new (...args: any[]) => Guard;
+/**
+ * A guard that reads the user id kept in the session at login (`Auth.login()`).
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options Loads the user of an id. Without it, the user is the id.
+ */
+export declare const sessionGuard: (options?: {
+    user?: (id: string) => unknown;
+}) => Guard;
+/**
+ * A guard that verifies a JSON Web Token from the `Authorization: Bearer` header.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options The key and the claims the token must carry, and a loader of the user from the
+ * claims. Without it, the user is the claims.
+ */
+export declare const jwtGuard: (options: JwtVerifyOptions & {
+    user?: (claims: Record<string, unknown>) => unknown;
+}) => Guard;
+/**
+ * A guard that finds the user of an API key, from a header (`x-api-key` by default) or the
+ * `Authorization: Bearer` header.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options Finds the user of a key from its hash (`ApiKeys.hash()`), and the header.
+ */
+export declare const apiKeyGuard: (options: {
+    find: (hash: string) => unknown;
+    header?: string;
+    /** Only bearer tokens with this prefix are API keys, such as `sk`. */
+    prefix?: string;
+}) => Guard;
+/**
+ * The options of `@Auth()`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type AuthOptions = {
+    /** The guards to try, in order, by their names in ThemisModule. Defaults to all of them. */
+    guards?: string[];
+    /** Lets requests without a user through; `Auth.user()` is then `undefined`. */
+    optional?: boolean;
+};
+/**
+ * Authenticates the requests of a route or a controller with the guards of ThemisModule, and puts
+ * the user in the request (`Auth.user()`, and `currentUser` in the context, which cerberus can
+ * read with `getSubject: (ctx) => ctx.currentUser`).
+ *
+ * It tries the guards named with `AuthMiddleware.guards([...])`, in order, or all of them.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @example
+ * ```ts
+ * @Middleware.register(AuthMiddleware.guards(['jwt']))
+ * class TokensController {}
+ * ```
+ */
+export declare class AuthMiddleware extends Middleware {
+    onBeforeHandle(context: HttpContext): Promise<void>;
+}
+/**
+ * Authenticates a controller or a route with {@link AuthMiddleware}: `guards` names the guards
+ * to try, and `optional` lets requests without a user through.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function Auth(options?: AuthOptions): ClassDecorator & MethodDecorator;
+export declare namespace Auth {
+    /** The user of the current request, if any. */
+    const user: <T = unknown>() => T | undefined;
+    /** The name of the guard that found the user of the current request. */
+    const guard: () => string | undefined;
+    /** Whether the current request has a user. */
+    const check: () => boolean;
+    /**
+     * Logs a user in for the session guard: gives the session a new id, against session fixation,
+     * and keeps the user id in it.
+     * @param id The user id.
+     */
+    const login: (id: string) => void;
+    /** Logs the user of the session out, ending the session. */
+    const logout: () => void;
+}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+import type { Guard, GuardClass } from './auth';
+import type { CookieOptions } from './context';
+import type { SessionStore } from './session';
+/** The service name of the Themis configuration. */
+export declare const THEMIS_CONFIG = "themis.settings";
+/**
+ * The configuration of ThemisModule.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ThemisConfig = {
+    /**
+     * The secret that signs the session cookie, encrypts cookie sessions and binds CSRF tokens. At
+     * least 32 random characters, kept out of the code (an environment secret).
+     */
+    secret: string;
+    /** The sessions. */
+    session?: {
+        /** Where sessions live. `cookie` keeps the whole session in an encrypted cookie. Defaults to memory. */
+        store?: SessionStore | 'cookie';
+        /** The session cookie. Its name defaults to `elysium_session`. */
+        cookie?: CookieOptions;
+        /** How long a session lives without being saved, in seconds. Defaults to 7 days. */
+        ttl?: number;
+    };
+    /**
+     * The guards `@Auth()` can use, by name: guard objects, or guard classes built through the
+     * service container. `@Auth()` without guards tries them all, in order.
+     */
+    guards?: Record<string, Guard | GuardClass>;
+    /** CSRF protection of cookie sessions. */
+    csrf?: {
+        /** The header that carries the token. Defaults to `x-csrf-token`. */
+        header?: string;
+        /** The body field that carries the token. Defaults to `_csrf`. */
+        field?: string;
+    };
+};

package/dist/context.d.ts

@@ -0,0 +1,42 @@
+import type { ThemisConfig } from './config';
+/** The request context of the current request, shared by its middlewares and its handler. */
+export type HttpContext = {
+    request: Request;
+    set: {
+        status?: number | string;
+        headers: Record<string, string | number | string[]>;
+    };
+    body?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * The context of the current request.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const currentContext: () => HttpContext | undefined;
+/**
+ * The configuration of ThemisModule.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const themisConfig: () => ThemisConfig;
+/** The value of a cookie of a request. */
+export declare const readCookie: (request: Request, name: string) => string | undefined;
+/**
+ * The attributes of a cookie.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type CookieOptions = {
+    name?: string;
+    path?: string;
+    domain?: string;
+    /** Defaults to `true`. Set it to `false` for local HTTP development only. */
+    secure?: boolean;
+    /** Defaults to `true`. */
+    httpOnly?: boolean;
+    /** Defaults to `Lax`. */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+};
+/** Adds a `Set-Cookie` header to the response of a context. */
+export declare const writeCookie: (context: HttpContext, name: string, value: string, options: CookieOptions & {
+    maxAge?: number;
+}) => void;

package/dist/crypto.d.ts

@@ -0,0 +1,38 @@
+/** The bytes of a string, as UTF-8. */
+export declare const utf8: (value: string) => Uint8Array<ArrayBuffer>;
+/** The string of UTF-8 bytes. */
+export declare const fromUtf8: (bytes: Uint8Array) => string;
+/** Random bytes from the platform's cryptographic generator. */
+export declare const randomBytes: (length: number) => Uint8Array<ArrayBuffer>;
+/** Bytes as base64url, without padding. */
+export declare const toBase64Url: (bytes: Uint8Array) => string;
+/** The bytes of a base64url (or base64) string. */
+export declare const fromBase64Url: (value: string) => Uint8Array<ArrayBuffer>;
+/** Bytes as lower-case hex. */
+export declare const toHex: (bytes: Uint8Array) => string;
+/** A random token: `bytes` random bytes as base64url. */
+export declare const randomToken: (bytes?: number) => string;
+/**
+ * Compares two strings in a time that does not depend on where they differ. Their lengths are not
+ * secret.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const safeEqual: (a: string, b: string) => boolean;
+/** The hex SHA-256 of a string. */
+export declare const sha256: (value: string) => Promise<string>;
+/** The base64url HMAC-SHA256 of a value. */
+export declare const hmac: (secret: string, value: string) => Promise<string>;
+/** Whether a base64url signature is the HMAC-SHA256 of a value. */
+export declare const verifyHmac: (secret: string, value: string, signature: string) => Promise<boolean>;
+/**
+ * Encrypts and authenticates a string with AES-256-GCM, under a key derived from a secret for a
+ * purpose. The result is base64url: the 12-byte IV, then the ciphertext and its tag.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const encrypt: (secret: string, purpose: string, plaintext: string) => Promise<string>;
+/**
+ * Decrypts a value of {@link encrypt}, or answers `null` when it was tampered with or sealed under
+ * another secret.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const decrypt: (secret: string, purpose: string, sealed: string) => Promise<string | null>;

package/dist/csrf.d.ts

@@ -0,0 +1,19 @@
+import type { HttpContext } from './context';
+import { Middleware } from '@elysiumjs/core';
+import { Session } from './session';
+/**
+ * Protects cookie sessions against cross-site request forgery. Unsafe requests (not `GET`, `HEAD`
+ * or `OPTIONS`) that carry a valid session cookie need the session's token in the `x-csrf-token`
+ * header or the `_csrf` body field. Requests without one, such as those of bearer tokens, are not
+ * checked. Register it after SessionMiddleware.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class CsrfMiddleware extends Middleware {
+    onBeforeHandle(context: HttpContext): Promise<void>;
+}
+export declare namespace Csrf {
+    /** The CSRF token of a session, created on first use. */
+    const tokenOf: (session: Session) => string;
+    /** The CSRF token of the current session, to put in forms or in a meta tag. */
+    const token: () => string;
+}

package/dist/errors.d.ts

@@ -0,0 +1,86 @@
+import { ElysiumError } from '@elysiumjs/core';
+export { UnauthenticatedError } from '@elysiumjs/core';
+declare const CsrfTokenMismatchError_base: {
+    new (detail?: string, options?: import("@elysiumjs/core").DomainErrorOptions): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        value?(): import("elysia/types").MaybePromise<unknown>;
+        readonly code: "CSRF_TOKEN_MISMATCH";
+        readonly status: 403;
+        readonly detail: string | undefined;
+        readonly title: string;
+        readonly errors: readonly import("@elysiumjs/core").ProblemValidationError[] | undefined;
+        readonly retryAfterSeconds: number | undefined;
+        readonly extensions: Readonly<Record<string, unknown>>;
+        readonly headers: Record<string, string> | undefined;
+        readonly type: string;
+        extension(): Record<string, unknown>;
+    };
+    isError(error: unknown): error is Error;
+    isError(value: unknown): value is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+    id<const Type extends string>(code: Type): import("elysia").TaggedHTTPError<Type>;
+    id<const Type extends string, const S_1 extends number | keyof import("elysia").StatusMap>(code: Type, status: S_1): import("elysia").TaggedHTTPError<Type, {
+        readonly status: S_1 extends keyof import("elysia").StatusMap ? import("elysia").StatusMap[S_1] : S_1;
+    }>;
+    typeBase?: string;
+    for<const C extends import("@elysiumjs/core").ProblemCode, const S extends number>(code: C, status: S): any;
+};
+/**
+ * Raised when an unsafe request of a cookie session carries no valid CSRF token. Rendered as a 403
+ * problem.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class CsrfTokenMismatchError extends CsrfTokenMismatchError_base {
+    constructor();
+}
+/**
+ * Raised when Themis is used without ThemisModule.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MissingThemisConfigError extends ElysiumError {
+    constructor();
+}
+/**
+ * Raised when the session is read outside a request, or without SessionMiddleware.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class NoSessionError extends ElysiumError {
+    constructor();
+}
+/**
+ * Raised when `@Auth()` names a guard that ThemisModule does not configure.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class UnknownGuardError extends ElysiumError {
+    constructor(name: string);
+}
+/**
+ * Raised when a secret is shorter than 32 bytes, which would let an attacker forge cookies,
+ * tokens or links by brute force.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class WeakSecretError extends ElysiumError {
+    constructor(what: string);
+}
+/** The shortest secret themis accepts, in bytes. */
+export declare const MIN_SECRET_BYTES = 32;
+/**
+ * Throws {@link WeakSecretError} for a secret under {@link MIN_SECRET_BYTES} bytes.
+ * @param secret The secret.
+ * @param what What the secret is for, in the message.
+ */
+export declare const assertStrongSecret: (secret: string, what: string) => void;
+/**
+ * Raised when a cookie session grows past what browsers keep (about 4 KB), which would silently
+ * lose it. Keep large data in a session store instead.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class SessionTooLargeError extends ElysiumError {
+    constructor(size: number);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { ApiKeys } from './api-keys';
+export { apiKeyGuard, Auth, AuthMiddleware, type AuthOptions, type Guard, type GuardClass, jwtGuard, sessionGuard } from './auth';
+export { THEMIS_CONFIG, type ThemisConfig } from './config';
+export { type CookieOptions, type HttpContext } from './context';
+export { Csrf, CsrfMiddleware } from './csrf';
+export { CsrfTokenMismatchError, MIN_SECRET_BYTES, MissingThemisConfigError, NoSessionError, SessionTooLargeError, UnauthenticatedError, UnknownGuardError, WeakSecretError } from './errors';
+export { InvalidTokenError, Jwt, type JwtKey, type JwtSignOptions, type JwtVerifyOptions } from './jwt';
+export { BunPasswordHasher, Password, type PasswordHasher, Pbkdf2PasswordHasher } from './password';
+export { commitSession, loadSession, MemorySessionStore, Session, type SessionData, SessionMiddleware, type SessionStore } from './session';
+export { OAuthCallbackError, OAuthClient, type OAuthClientOptions, type OAuthResult } from './oauth';
+export { type PasskeyRecord, type PasskeyRepository, Passkeys, type PasskeysOptions, PasskeyVerificationError } from './passkeys';
+export { InvalidSignatureError, SignedUrl } from './signed-url';
+export { ThemisModule } from './themis.module';
+export { BackupCodes, Totp, type TotpOptions } from './totp';