@owlmeans/auth-email 0.0.0-stage → 0.1.19

package/build/errors.js

@@ -0,0 +1,66 @@
+import { ResilientError } from '@owlmeans/error';
+/**
+ * The e-mail sign-in error family, shared by the server that throws and the client that reads it
+ * back (each class is registered, so it survives the wire). A failed PIN or password check is
+ * `AuthenFailed` from `@owlmeans/auth`, never one of these: no answer here may tell an unknown
+ * address from a wrong credential.
+ */
+export class EmailAuthError extends ResilientError {
+    static typeName = 'EmailAuthError';
+    constructor(message = 'error') {
+        super(EmailAuthError.typeName, `auth-email:${message}`);
+    }
+}
+/** A password sign-in or a password route on a deployment that does not offer passwords. */
+export class EmailPasswordDisabled extends EmailAuthError {
+    static typeName = `${EmailAuthError.typeName}PasswordDisabled`;
+    static httpStatus = 404;
+    constructor(message = 'password') {
+        super(`disabled:${message}`);
+        this.type = EmailPasswordDisabled.typeName;
+    }
+}
+/** A new password the policy refuses (length bounds); the message names the rule. */
+export class EmailPasswordWeak extends EmailAuthError {
+    static typeName = `${EmailAuthError.typeName}PasswordWeak`;
+    static httpStatus = 422;
+    constructor(message = 'length') {
+        super(`weak:${message}`);
+        this.type = EmailPasswordWeak.typeName;
+    }
+}
+/** The one-use offer ticket is spent, expired or another account's — confirm with a PIN instead. */
+export class EmailOfferExpired extends EmailAuthError {
+    static typeName = `${EmailAuthError.typeName}OfferExpired`;
+    static httpStatus = 409;
+    constructor(message = 'offer') {
+        super(`expired:${message}`);
+        this.type = EmailOfferExpired.typeName;
+    }
+}
+/** A developer (tech) route on a deployment where they are off: answers as if it did not exist. */
+export class EmailTechDisabled extends EmailAuthError {
+    static typeName = `${EmailAuthError.typeName}TechDisabled`;
+    static httpStatus = 404;
+    constructor(message = 'tech') {
+        super(`disabled:${message}`);
+        this.type = EmailTechDisabled.typeName;
+    }
+}
+/** A store, mailer or captcha authority could not be consulted, so the request fails closed. */
+export class EmailAuthUnavailable extends EmailAuthError {
+    static typeName = `${EmailAuthError.typeName}Unavailable`;
+    static httpStatus = 503;
+    static allowServerErrorStatus = true;
+    constructor(message = 'unavailable') {
+        super(`unavailable:${message}`);
+        this.type = EmailAuthUnavailable.typeName;
+    }
+}
+ResilientError.registerErrorClass(EmailAuthError);
+ResilientError.registerErrorClass(EmailPasswordDisabled);
+ResilientError.registerErrorClass(EmailPasswordWeak);
+ResilientError.registerErrorClass(EmailOfferExpired);
+ResilientError.registerErrorClass(EmailTechDisabled);
+ResilientError.registerErrorClass(EmailAuthUnavailable);
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,cAAc;IACzC,MAAM,CAAU,QAAQ,GAAW,gBAAgB,CAAA;IAE1D,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,cAAc,CAAC,QAAQ,EAAE,cAAc,OAAO,EAAE,CAAC,CAAA;IACzD,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IAChD,MAAM,CAAU,QAAQ,GAAW,GAAG,cAAc,CAAC,QAAQ,kBAAkB,CAAA;IAC/E,MAAM,CAAC,UAAU,GAAG,GAAG,CAAA;IAE9B,YAAY,OAAO,GAAW,UAAU;QACtC,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC,QAAQ,CAAA;IAC5C,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IAC5C,MAAM,CAAU,QAAQ,GAAW,GAAG,cAAc,CAAC,QAAQ,cAAc,CAAA;IAC3E,MAAM,CAAC,UAAU,GAAG,GAAG,CAAA;IAE9B,YAAY,OAAO,GAAW,QAAQ;QACpC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAA;IACxC,CAAC;CACF;AAED,oGAAoG;AACpG,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IAC5C,MAAM,CAAU,QAAQ,GAAW,GAAG,cAAc,CAAC,QAAQ,cAAc,CAAA;IAC3E,MAAM,CAAC,UAAU,GAAG,GAAG,CAAA;IAE9B,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,WAAW,OAAO,EAAE,CAAC,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAA;IACxC,CAAC;CACF;AAED,mGAAmG;AACnG,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IAC5C,MAAM,CAAU,QAAQ,GAAW,GAAG,cAAc,CAAC,QAAQ,cAAc,CAAA;IAC3E,MAAM,CAAC,UAAU,GAAG,GAAG,CAAA;IAE9B,YAAY,OAAO,GAAW,MAAM;QAClC,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAA;IACxC,CAAC;CACF;AAED,gGAAgG;AAChG,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IAC/C,MAAM,CAAU,QAAQ,GAAW,GAAG,cAAc,CAAC,QAAQ,aAAa,CAAA;IAC1E,MAAM,CAAC,UAAU,GAAG,GAAG,CAAA;IACvB,MAAM,CAAC,sBAAsB,GAAG,IAAI,CAAA;IAE3C,YAAY,OAAO,GAAW,aAAa;QACzC,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAA;IAC3C,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAA;AACxD,cAAc,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AACpD,cAAc,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AACpD,cAAc,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AACpD,cAAc,CAAC,kBAAkB,CAAC,oBAAoB,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './schemas.js';
+export * from './errors.js';
+export * from './entrypoints.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA"}

package/build/index.js

@@ -0,0 +1,5 @@
+export * from './consts.js';
+export * from './schemas.js';
+export * from './errors.js';
+export * from './entrypoints.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA"}

package/build/schemas.d.ts

@@ -0,0 +1,12 @@
+import type { JSONSchemaType } from 'ajv';
+import type { EmailEmptyRequest, EmailPasswordPinRequest, EmailPasswordRemoveRequest, EmailPasswordSetRequest, EmailPinRequest, EmailSignInRequest, EmailTechPinRequest } from './types.js';
+export declare const EmailPinRequestSchema: JSONSchemaType<EmailPinRequest>;
+/** One schema for both modes; the server enforces exactly one of PIN (`challenge` + `pin`) or `password`. */
+export declare const EmailSignInRequestSchema: JSONSchemaType<EmailSignInRequest>;
+export declare const EmailPasswordPinRequestSchema: JSONSchemaType<EmailPasswordPinRequest>;
+export declare const EmailPasswordSetRequestSchema: JSONSchemaType<EmailPasswordSetRequest>;
+export declare const EmailPasswordRemoveRequestSchema: JSONSchemaType<EmailPasswordRemoveRequest>;
+export declare const EmailTechPinRequestSchema: JSONSchemaType<EmailTechPinRequest>;
+/** The body of `password/decline` and `tech/waiver`: an empty object. */
+export declare const EmailEmptyRequestSchema: JSONSchemaType<EmailEmptyRequest>;
+//# sourceMappingURL=schemas.d.ts.map

package/build/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AAKzC,OAAO,KAAK,EACV,iBAAiB,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,uBAAuB,EAC/F,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EACzD,MAAM,YAAY,CAAA;AAYnB,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,eAAe,CASjE,CAAA;AAED,6GAA6G;AAC7G,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,kBAAkB,CAavE,CAAA;AAED,eAAO,MAAM,6BAA6B,EAAE,cAAc,CAAC,uBAAuB,CAQjF,CAAA;AAED,eAAO,MAAM,6BAA6B,EAAE,cAAc,CAAC,uBAAuB,CAWjF,CAAA;AAED,eAAO,MAAM,gCAAgC,EAAE,cAAc,CAAC,0BAA0B,CASvF,CAAA;AAED,eAAO,MAAM,yBAAyB,EAAE,cAAc,CAAC,mBAAmB,CAKzE,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,EAKpB,cAAc,CAAC,iBAAiB,CAAC,CAAA"}

package/build/schemas.js

@@ -0,0 +1,79 @@
+import { EMAIL_ADDRESS_MAX_LENGTH, EMAIL_DEVICE_ID_PATTERN, EMAIL_LOCALE_MAX_LENGTH, EMAIL_PASSWORD_WIRE_MAX_LENGTH, EMAIL_PIN_PATTERN, EMAIL_TOKEN_MAX_LENGTH, EmailPasswordPurpose, } from './consts.js';
+// Every request schema refuses unknown fields; no body carries an organization or a source.
+// The address is lowercased and trimmed by the server; the password policy is checked there too.
+const email = { type: 'string', format: 'email', minLength: 3, maxLength: EMAIL_ADDRESS_MAX_LENGTH };
+const device = { type: 'string', pattern: EMAIL_DEVICE_ID_PATTERN };
+const pin = { type: 'string', pattern: EMAIL_PIN_PATTERN };
+const token = { type: 'string', minLength: 1, maxLength: EMAIL_TOKEN_MAX_LENGTH };
+const password = { type: 'string', minLength: 1, maxLength: EMAIL_PASSWORD_WIRE_MAX_LENGTH };
+const locale = { type: 'string', minLength: 1, maxLength: EMAIL_LOCALE_MAX_LENGTH };
+export const EmailPinRequestSchema = {
+    type: 'object',
+    properties: {
+        email,
+        locale: { ...locale, nullable: true },
+        captcha: { ...token, nullable: true },
+    },
+    required: ['email'],
+    additionalProperties: false,
+};
+/** One schema for both modes; the server enforces exactly one of PIN (`challenge` + `pin`) or `password`. */
+export const EmailSignInRequestSchema = {
+    type: 'object',
+    properties: {
+        email,
+        device,
+        challenge: { ...token, nullable: true },
+        pin: { ...pin, nullable: true },
+        password: { ...password, nullable: true },
+        captcha: { ...token, nullable: true },
+        locale: { ...locale, nullable: true },
+    },
+    required: ['email', 'device'],
+    additionalProperties: false,
+};
+export const EmailPasswordPinRequestSchema = {
+    type: 'object',
+    properties: {
+        purpose: { type: 'string', enum: Object.values(EmailPasswordPurpose) },
+        locale: { ...locale, nullable: true },
+    },
+    required: ['purpose'],
+    additionalProperties: false,
+};
+export const EmailPasswordSetRequestSchema = {
+    type: 'object',
+    properties: {
+        password,
+        offer: { ...token, nullable: true },
+        challenge: { ...token, nullable: true },
+        pin: { ...pin, nullable: true },
+        device: { ...device, nullable: true },
+    },
+    required: ['password'],
+    additionalProperties: false,
+};
+export const EmailPasswordRemoveRequestSchema = {
+    type: 'object',
+    properties: {
+        challenge: token,
+        pin,
+        device: { ...device, nullable: true },
+    },
+    required: ['challenge', 'pin'],
+    additionalProperties: false,
+};
+export const EmailTechPinRequestSchema = {
+    type: 'object',
+    properties: { challenge: token, pin },
+    required: ['challenge', 'pin'],
+    additionalProperties: false,
+};
+/** The body of `password/decline` and `tech/waiver`: an empty object. */
+export const EmailEmptyRequestSchema = {
+    type: 'object',
+    properties: {},
+    required: [],
+    additionalProperties: false,
+};
+//# sourceMappingURL=schemas.js.map

package/build/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,173 @@
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint';
+import type { RouteParent } from '@owlmeans/route';
+import type { EMAIL_AUTH_LOCALES, EMAIL_CAPTCHA_PROVIDER, EmailPasswordPurpose, EmailSignInReason } from './consts.js';
+/** One of the languages the sign-in mails are written in. */
+export type EmailAuthLocale = typeof EMAIL_AUTH_LOCALES[number];
+/** The captcha a client must solve before send-PIN and password sign-in. */
+export interface EmailAuthCaptchaView {
+    provider: typeof EMAIL_CAPTCHA_PROVIDER;
+    siteKey: string;
+}
+/** `GET options` — what this deployment offers; asks for no address. */
+export interface EmailAuthOptionsView {
+    /** Password sign-in and the password routes are served. */
+    password: boolean;
+    /** `null` when captcha is off (or a valid developer waiver came with the request). */
+    captcha: EmailAuthCaptchaView | null;
+    pinLength: number;
+}
+/** A PIN was mailed: the signed challenge to send back with it. */
+export interface EmailChallengeView {
+    challenge: string;
+}
+/**
+ * `POST sign-in`. A signed-in answer carries `token` (and, after a PIN sign-in of a person without
+ * a password who has not declined one, the one-use `offer` ticket); a password sign-in on an
+ * unknown device carries `challenge` + `reason: device` instead — a PIN was mailed and the password
+ * was not checked.
+ */
+export interface EmailSignInView {
+    token?: string;
+    offer?: string;
+    challenge?: string;
+    reason?: EmailSignInReason;
+}
+/** The signed-in account's password state. */
+export interface EmailPasswordStatusView {
+    /** Passwords are enabled on this deployment. */
+    enabled: boolean;
+    set: boolean;
+    /** The person declined the post-sign-in offer (or removed their password). */
+    declined: boolean;
+    /** ISO time of the last set/change/remove. */
+    updatedAt?: string;
+}
+export interface EmailTechPinView {
+    ok: boolean;
+}
+/** A developer waiver: send `waiver` in `EMAIL_WAIVER_HEADER` until `expiresAt` (ISO time). */
+export interface EmailTechWaiverView {
+    waiver: string;
+    expiresAt: string;
+}
+/** A body with no fields (decline, waiver). */
+export type EmailEmptyRequest = Record<string, never>;
+/** `POST pin` — mail a sign-in PIN; the same answer for a known and a new address. */
+export interface EmailPinRequest {
+    email: string;
+    locale?: string;
+    captcha?: string;
+}
+/**
+ * `POST sign-in` — ONE body for both modes: PIN mode sends `challenge` + `pin`, password mode
+ * sends `password` (+ `captcha`). The server accepts exactly one mode.
+ */
+export interface EmailSignInRequest {
+    email: string;
+    /** The browser's device id (`EMAIL_DEVICE_ID_PATTERN`). */
+    device: string;
+    challenge?: string;
+    pin?: string;
+    password?: string;
+    captcha?: string;
+    locale?: string;
+}
+/** `POST password/pin` — mail a confirmation PIN to the account's own address. */
+export interface EmailPasswordPinRequest {
+    purpose: EmailPasswordPurpose;
+    locale?: string;
+}
+/**
+ * `POST password/set` — confirmed either by the `offer` ticket of a fresh PIN sign-in or by a
+ * `challenge` + `pin` from `password/pin`. `device` keeps the current browser remembered while the
+ * account's other devices are forgotten.
+ */
+export interface EmailPasswordSetRequest {
+    password: string;
+    offer?: string;
+    challenge?: string;
+    pin?: string;
+    device?: string;
+}
+/** `POST password/remove` — confirmed by a `challenge` + `pin` from `password/pin`. */
+export interface EmailPasswordRemoveRequest {
+    challenge: string;
+    pin: string;
+    device?: string;
+}
+/** `POST tech/pin` — a developer replaces the PIN of a pending challenge. */
+export interface EmailTechPinRequest {
+    challenge: string;
+    pin: string;
+}
+export interface EmailAuthGateOption {
+    alias: string;
+    params?: string | readonly string[];
+}
+/**
+ * The guest routes (`options`, `pin`, `sign-in`) are never guarded by this factory. The password
+ * routes need the application's session: `guards` (+ `gate`), or a `passwordParent` whose guards
+ * they inherit — neither is a declaration error. The developer (tech) routes default to
+ * `GUARD_ED25519` + the `EMAIL_AUTH_TECH_GATE` gate.
+ */
+export interface EmailAuthEntrypointOptions {
+    /** The guest base path; default `EMAIL_AUTH_API_PATH`. */
+    path?: string;
+    /** The guest base's parent route. */
+    parent?: RouteParent;
+    /** Guards of the password subtree. */
+    guards?: string | readonly string[];
+    /** Gate of the password subtree. */
+    gate?: EmailAuthGateOption;
+    /** Mount the password subtree (`/password`) under this route instead of the guest base. */
+    passwordParent?: RouteParent;
+    /** Guards of the tech subtree; default `[GUARD_ED25519]`. */
+    techGuards?: string | readonly string[];
+    /** Gate of the tech subtree; default `{ alias: EMAIL_AUTH_TECH_GATE }`. */
+    techGate?: EmailAuthGateOption;
+    /** The offer screen; default path `EMAIL_AUTH_OFFER_PATH`, top-level. */
+    screen?: {
+        path?: string;
+        parent?: RouteParent;
+    };
+}
+export interface EmailPasswordEntrypoints {
+    base: EntrypointProtocol<OpenRequest, OpenValue>;
+    status: EntrypointProtocol<{}, EmailPasswordStatusView>;
+    pin: EntrypointProtocol<{
+        body: EmailPasswordPinRequest;
+    }, EmailChallengeView>;
+    set: EntrypointProtocol<{
+        body: EmailPasswordSetRequest;
+    }, EmailPasswordStatusView>;
+    remove: EntrypointProtocol<{
+        body: EmailPasswordRemoveRequest;
+    }, EmailPasswordStatusView>;
+    decline: EntrypointProtocol<{
+        body: EmailEmptyRequest;
+    }, EmailPasswordStatusView>;
+}
+export interface EmailTechEntrypoints {
+    base: EntrypointProtocol<OpenRequest, OpenValue>;
+    pin: EntrypointProtocol<{
+        body: EmailTechPinRequest;
+    }, EmailTechPinView>;
+    waiver: EntrypointProtocol<{
+        body: EmailEmptyRequest;
+    }, EmailTechWaiverView>;
+}
+export interface EmailAuthEntrypoints {
+    base: EntrypointProtocol<OpenRequest, OpenValue>;
+    options: EntrypointProtocol<{}, EmailAuthOptionsView>;
+    pin: EntrypointProtocol<{
+        body: EmailPinRequest;
+    }, EmailChallengeView>;
+    signIn: EntrypointProtocol<{
+        body: EmailSignInRequest;
+    }, EmailSignInView>;
+    password: EmailPasswordEntrypoints;
+    tech: EmailTechEntrypoints;
+    /** The post-sign-in "set a password" screen — frontend, sticky. */
+    offer: EntrypointProtocol<OpenRequest, OpenValue>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@owlmeans/auth-email",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.19",
+  "license": "MIT",
+  "description": "Contracts of OwlMeans e-mail sign-in — PIN, optional password, remembered devices, captcha: the protocol factory, schemas, views, constants and errors.",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 2 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/auth": "^0.1.19",
+    "@owlmeans/auth-common": "^0.1.19",
+    "@owlmeans/context": "^0.1.19",
+    "@owlmeans/entrypoint": "^0.1.19",
+    "@owlmeans/error": "^0.1.19",
+    "@owlmeans/route": "^0.1.19"
+  },
+  "peerDependencies": {
+    "ajv": "*",
+    "ajv-formats": "*"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "^0.1.19",
+    "@types/bun": "^1.4.2",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,107 @@
+// --- Methods, auth types and envelopes ---------------------------------------------------------
+
+/** The client `AuthenticationPlugin` type and the login method id of e-mail sign-in. */
+export const EMAIL_LOGIN_METHOD = 'email'
+
+/** The private server plugin of a PIN sign-in, and the type its signed token carries. */
+export const EMAIL_PIN_AUTH_TYPE = 'email-pin'
+
+/** The private server plugin of a password sign-in, and the type its signed token carries. */
+export const EMAIL_PASSWORD_AUTH_TYPE = 'email-password'
+
+/** A purpose-bound confirmation challenge (set, change or remove a password). */
+export const EMAIL_CONFIRM_ENVELOPE = 'email-confirm'
+
+/** A developer's captcha and throttle waiver. */
+export const EMAIL_WAIVER_ENVELOPE = 'email-waiver'
+
+/** The request header that carries an `EMAIL_WAIVER_ENVELOPE`. */
+export const EMAIL_WAIVER_HEADER = 'x-owlmeans-email-waiver'
+
+/** The captcha action of a send-PIN request. */
+export const EMAIL_CAPTCHA_ACTION_PIN = 'email_pin'
+
+/** The captcha action of a password sign-in. */
+export const EMAIL_CAPTCHA_ACTION_PASSWORD = 'email_password'
+
+/**
+ * The identity-linking details type of an account's e-mail credential — the same value as
+ * `OTP_AUTH_TYPE` (`@owlmeans/auth-otp`), so e-mail sign-in and e-mail OTP land on one account.
+ * It names a credential, never a token type.
+ */
+export const EMAIL_IDENTITY_TYPE = 'email-otp'
+
+/** The captcha provider an options view may name. */
+export const EMAIL_CAPTCHA_PROVIDER = 'recaptcha-v3'
+
+// --- Policy ------------------------------------------------------------------------------------
+
+/** Digits in a PIN — the same as `OTP_CODE_LENGTH` (`@owlmeans/auth-otp`). */
+export const EMAIL_PIN_LENGTH = 6
+export const EMAIL_PIN_PATTERN = '^[0-9]{6}$'
+
+/** How long a device stays remembered after a successful sign-in on it. */
+export const EMAIL_DEVICE_TTL_DAYS = 30
+/** Remembered devices per account; the oldest beyond it are forgotten. */
+export const EMAIL_DEVICE_LIMIT = 10
+/** A device id: 22 base64url characters (16 random bytes) from the client, up to 64 accepted. */
+export const EMAIL_DEVICE_ID_PATTERN = '^[A-Za-z0-9_-]{22,64}$'
+
+/** Lifetime of the one-use "set a password" offer ticket a PIN sign-in returns. */
+export const EMAIL_OFFER_TTL_SECONDS = 900
+/** Lifetime of a developer waiver. */
+export const EMAIL_WAIVER_TTL_SECONDS = 7200
+
+export const EMAIL_PASSWORD_MIN_LENGTH = 8
+export const EMAIL_PASSWORD_MAX_LENGTH = 128
+
+/** Wire bounds of the request fields (the password policy above is checked by the server). */
+export const EMAIL_ADDRESS_MAX_LENGTH = 254
+export const EMAIL_PASSWORD_WIRE_MAX_LENGTH = 1024
+export const EMAIL_TOKEN_MAX_LENGTH = 4096
+export const EMAIL_LOCALE_MAX_LENGTH = 16
+
+/** The languages the sign-in mails are written in; any other locale falls back to `en`. */
+export const EMAIL_AUTH_LOCALES = Object.freeze(['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'] as const)
+
+export enum EmailPasswordPurpose {
+  Set = 'set',
+  Change = 'change',
+  Remove = 'remove',
+}
+
+export enum EmailSignInReason {
+  /** The password was not checked: the device is unknown, so a PIN was mailed instead. */
+  Device = 'device',
+}
+
+// --- Service aliases ---------------------------------------------------------------------------
+
+/** The server service alias. */
+export const EMAIL_AUTH_SERVICE = 'auth-email'
+/** The client service alias. */
+export const EMAIL_LOGIN_SERVICE = 'auth-email-client'
+/** The gate service standing over the developer (tech) routes. */
+export const EMAIL_AUTH_TECH_GATE = 'auth-email:tech-gate'
+
+// --- Paths -------------------------------------------------------------------------------------
+
+export const EMAIL_AUTH_API_PATH = '/auth/email'
+export const EMAIL_AUTH_OFFER_PATH = '/login/password'
+
+// --- Protocol tree aliases ---------------------------------------------------------------------
+
+export const EMAIL_AUTH_BASE = 'auth-email:base'
+export const EMAIL_AUTH_OPTIONS = 'auth-email:options'
+export const EMAIL_AUTH_PIN = 'auth-email:pin'
+export const EMAIL_AUTH_SIGN_IN = 'auth-email:sign-in'
+export const EMAIL_AUTH_PASSWORD = 'auth-email:password'
+export const EMAIL_AUTH_PASSWORD_STATUS = 'auth-email:password:status'
+export const EMAIL_AUTH_PASSWORD_PIN = 'auth-email:password:pin'
+export const EMAIL_AUTH_PASSWORD_SET = 'auth-email:password:set'
+export const EMAIL_AUTH_PASSWORD_REMOVE = 'auth-email:password:remove'
+export const EMAIL_AUTH_PASSWORD_DECLINE = 'auth-email:password:decline'
+export const EMAIL_AUTH_TECH = 'auth-email:tech'
+export const EMAIL_AUTH_TECH_PIN = 'auth-email:tech:pin'
+export const EMAIL_AUTH_TECH_WAIVER = 'auth-email:tech:waiver'
+export const EMAIL_AUTH_OFFER = 'auth-email:offer'