@arkstack/common 0.17.26 → 0.18.1

package/README.md

@@ -515,9 +515,9 @@ Clears all registered hooks.
 
 **`src/utils/encryption.ts`**
 
-AES-256-GCM symmetric encryption for sensitive values (e.g. two-factor authentication secrets). Requires the `TWO_FACTOR_ENCRYPTION_KEY` environment variable.
+A thin wrapper around [`@arkstack/encryption`](https://www.npmjs.com/package/@arkstack/encryption), bound to the application key. AES-256-GCM for sensitive values (e.g. two-factor authentication secrets); the package underneath runs on the Web Crypto API, so a value encrypted on the server can be decrypted in the browser and vice versa.
 
-#### `Encryption.encrypt(value)`
+#### `Encryption.encrypt(value, key?)`
 
 Encrypts a string. Returns a colon-delimited base64url string: `<iv>:<authTag>:<ciphertext>`.
 
@@ -528,7 +528,9 @@ const token = Encryption.encrypt('my-secret-value');
 // "abc123:def456:ghi789"
 ```
 
-#### `Encryption.decrypt(payload)`
+---
+
+#### `Encryption.decrypt(payload, key?)`
 
 Decrypts a payload produced by `encrypt`. Throws if the format is invalid or the key is wrong.
 
@@ -537,11 +539,54 @@ const original = Encryption.decrypt(token);
 // "my-secret-value"
 ```
 
+---
+
+#### `Encryption.encryptAsync(value, key?, options?)` / `Encryption.decryptAsync(payload, key?, options?)`
+
+The same operations on the Web Crypto path, in the same payload format, so the two can be mixed freely. Use these when the calling code is (or may become) shared with the browser. `options.aad` binds additional authenticated data to the ciphertext.
+
+---
+
+#### `Encryption.cipher(key?)`
+
+A `Cipher` bound to the application key, for encrypting many values without re-deriving the key, and for raw bytes via `encryptBytes` / `decryptBytes`.
+
+---
+
+#### Key utilities
+
+```ts
+Encryption.generateKey();                   // random base64url key
+await Encryption.generateKeyPair();         // { publicKey, privateKey } ECDH identity
+await Encryption.deriveKey(password);       // PBKDF2 → { key, salt, iterations }
+await Encryption.compareKeys(left, right);  // constant time
+await Encryption.fingerprint();             // displayable digest of the app key
+```
+
+---
+
+#### End-to-end encryption
+
+```ts
+const channel = await Encryption.channel(myPrivateKey, peerPublicKey);
+
+await channel.decrypt(await channel.encrypt('hey'));
+
+await Encryption.seal('anonymous tip', peerPublicKey);
+await Encryption.open(payload, myPrivateKey);
+
+await Encryption.safetyNumber(myPublicKey, peerPublicKey);
+```
+
+The full `@arkstack/encryption` surface — `Cipher`, `Codec`, `EncryptionKey`, `KeyPair`, `Keys`, `SealedBox`, `SecureChannel`, `NodeCipher` — is re-exported from this package.
+
 **Environment variable:**
 
-| Variable                    | Required | Description                                                |
-| --------------------------- | -------- | ---------------------------------------------------------- |
-| `TWO_FACTOR_ENCRYPTION_KEY` | Yes      | Raw secret; hashed to a 256-bit key internally via SHA-256 |
+| Variable  | Required | Description                                                |
+| --------- | -------- | ---------------------------------------------------------- |
+| `APP_KEY` | Yes      | Raw secret; hashed to a 256-bit key internally via SHA-256 |
+
+Generate one with `ark key:generate`. The legacy `TWO_FACTOR_ENCRYPTION_KEY` is still honored when `APP_KEY` is not set.
 
 ---
 

package/dist/{helpers-E_O2UDRn.d.ts → helpers-Bn-0uv3R.d.ts}

@@ -1,7 +1,9 @@
+import { ChannelOptions, Cipher, CipherOptions, Codec, DeriveOptions, DerivedKey, EncryptionKey, FingerprintOptions, KeyInput, KeyPair, Keys, SealedBox, SecureChannel, SerializedKeyPair } from "@arkstack/encryption";
+import { NodeCipher } from "@arkstack/encryption/node";
 import { JitiOptions, JitiResolveOptions } from "jiti";
 import { TOTP } from "otpauth";
+import { Model, ModelStatic, RegisteredModelClass, RegisteredModelName, RelatedModelClass } from "arkormx";
 import { ChalkInstance } from "chalk";
-import { Model, ModelStatic } from "arkormx";
 //#region src/Logger.d.ts
 declare class Console {
   static log: (...args: any[]) => string | void;
@@ -388,11 +390,160 @@ interface PublishConfirmation {
 }
 //#endregion
 //#region src/utils/encryption.d.ts
+/**
+ * Application facing encryption, bound to the app key.
+ *
+ * This is a thin wrapper over `@arkstack/encryption`. `encrypt()` and
+ * `decrypt()` keep the synchronous signatures and the exact payload format
+ * they have always had — `<iv>:<authTag>:<ciphertext>`, AES-256-GCM under
+ * SHA-256 of `APP_KEY` — so existing ciphertexts and call sites are unaffected.
+ *
+ * Everything else is new surface: the asynchronous methods run on the Web
+ * Crypto API, which means a browser holding the same key (or the same key pair
+ * peer) can decrypt what the server wrote, and the server can decrypt what the
+ * browser wrote.
+ */
 declare class Encryption {
-  private static readonly algorithm;
-  private static getKey;
-  static encrypt(value: string): string;
-  static decrypt(payload: string): string;
+  /**
+   * Encrypt a string with the application key.
+   *
+   * @param value
+   * @param key Override the application key for this call.
+   * @returns
+   */
+  static encrypt(value: string, key?: KeyInput): string;
+  /**
+   * Decrypt a payload produced by {@link encrypt}.
+   *
+   * @param payload
+   * @param key Override the application key for this call.
+   * @returns
+   */
+  static decrypt(payload: string, key?: KeyInput): string;
+  /**
+   * Encrypt through the isomorphic Web Crypto implementation.
+   *
+   * Produces the same payload format as {@link encrypt}; use it when the
+   * calling code is (or may become) shared with the browser.
+   *
+   * @param value
+   * @param key
+   * @param options
+   * @returns
+   */
+  static encryptAsync(value: string, key?: KeyInput, options?: CipherOptions): Promise<string>;
+  /**
+   * Decrypt through the isomorphic Web Crypto implementation.
+   *
+   * @param payload
+   * @param key
+   * @param options
+   * @returns
+   */
+  static decryptAsync(payload: string, key?: KeyInput, options?: CipherOptions): Promise<string>;
+  /**
+   * A cipher bound to the application key, for encrypting many values or raw
+   * bytes without re-deriving the key each time.
+   *
+   * @param key
+   * @returns
+   */
+  static cipher(key?: KeyInput): Promise<Cipher>;
+  /**
+   * The application key as it appears in the environment.
+   *
+   * Reads `APP_KEY`, falling back to the legacy `TWO_FACTOR_ENCRYPTION_KEY`
+   * variable. Override this in a subclass to source the key elsewhere.
+   *
+   * @returns
+   */
+  protected static secret(): string;
+  /**
+   * The 32 bytes of key material actually handed to the cipher: SHA-256 of
+   * the application key, or of an explicit override.
+   *
+   * The same bytes are reachable in the browser with
+   * `EncryptionKey.fromSecret(secret)`.
+   *
+   * @param key
+   * @returns
+   */
+  static material(key?: KeyInput): Uint8Array;
+  /**
+   * Generate a random base64url encryption key.
+   *
+   * @param length Key length in bytes, defaults to 32.
+   * @returns
+   */
+  static generateKey(length?: number): string;
+  /**
+   * Generate an end-to-end encryption identity. The public key is published,
+   * the private key stays with its owner.
+   *
+   * @returns
+   */
+  static generateKeyPair(): Promise<SerializedKeyPair>;
+  /**
+   * Stretch a user supplied password into a key with PBKDF2-HMAC-SHA256.
+   *
+   * @param password
+   * @param options
+   * @returns
+   */
+  static deriveKey(password: string, options?: DeriveOptions): Promise<DerivedKey>;
+  /**
+   * Constant time comparison of two keys.
+   *
+   * @param left
+   * @param right
+   * @returns
+   */
+  static compareKeys(left: KeyInput, right: KeyInput): Promise<boolean>;
+  /**
+   * A displayable digest of a key, safe to show to users or write to logs.
+   *
+   * @param key Defaults to the application key.
+   * @param options
+   * @returns
+   */
+  static fingerprint(key?: KeyInput, options?: FingerprintOptions): Promise<string>;
+  /**
+   * Open an end-to-end encrypted channel between a local private key and a
+   * peer's public key. Neither key, nor the secret they agree on, ever
+   * crosses the wire.
+   *
+   * @param privateKey
+   * @param peerPublicKey
+   * @param options
+   * @returns
+   */
+  static channel(privateKey: string | KeyPair, peerPublicKey: string | KeyPair, options?: ChannelOptions): Promise<SecureChannel>;
+  /**
+   * Encrypt a message to a public key without needing a sender identity.
+   *
+   * @param message
+   * @param recipientPublicKey
+   * @returns
+   */
+  static seal(message: string, recipientPublicKey: string | KeyPair): Promise<string>;
+  /**
+   * Open a payload produced by {@link seal}.
+   *
+   * @param payload
+   * @param recipientPrivateKey
+   * @returns
+   */
+  static open(payload: string, recipientPrivateKey: string | KeyPair): Promise<string>;
+  /**
+   * The safety number for a conversation between two public keys — show it to
+   * both participants so they can verify nobody swapped a key in transit.
+   *
+   * @param first
+   * @param second
+   * @param groups
+   * @returns
+   */
+  static safetyNumber(first: string, second: string, groups?: number): Promise<string>;
 }
 //#endregion
 //#region src/utils/hash.d.ts
@@ -428,7 +579,6 @@ declare class Hash {
 type AbstractModelConstructor<TModel = unknown> = abstract new (attributes?: Record<string, unknown>) => TModel;
 type ModelConstructor<TModel extends Model = Model> = AbstractModelConstructor<TModel> & Pick<ModelStatic<TModel>, keyof ModelStatic<TModel>>;
 interface ModelRegistry {}
-type ModelName = Extract<keyof ModelRegistry, string>;
 /**
  * Checks and asserts if target is a class
  *
@@ -474,15 +624,18 @@ declare const resolvePagination: (query: {
   maxPerPage?: number;
 }) => PaginationOptions;
 /**
- * Import an application model by name.
+ * Synchronously resolve an application model by name.
  *
- * Apps can augment `ModelRegistry` to make `getModel('User')` return `typeof User`.
- * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
+ * Registered models are returned first. If a model has not been registered yet,
+ * ArkORM loads it from the configured models paths, registers it, and returns
+ * the matching constructor.
  *
  * @param modelName
+ * @alias {@link getArkormxModel}
+ * @returns
  */
-declare function getModel<TName extends ModelName>(modelName: TName): Promise<ModelRegistry[TName]>;
-declare function getModel<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): Promise<TModel>;
+declare function getModel$1<TName extends RegisteredModelName>(modelName: TName): RegisteredModelClass<TName>;
+declare function getModel$1<TModel extends RelatedModelClass = RelatedModelClass>(modelName: string): TModel;
 /**
  * Synchronously import an application model by name.
  *
@@ -490,9 +643,11 @@ declare function getModel<TModel extends AbstractModelConstructor = ModelConstru
  * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
  *
  * @param modelName
+ * @alias {@link getArkormxModel}
+ * @deprecated 0.17.27 - Use {@link getModel} or {@link getArkormxModel}
  */
-declare function getModelSync<TName extends ModelName>(modelName: TName): ModelRegistry[TName];
-declare function getModelSync<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): TModel;
+declare function getModelSync<TName extends RegisteredModelName>(modelName: TName): RegisteredModelClass<TName>;
+declare function getModelSync<TModel extends RelatedModelClass = RelatedModelClass>(modelName: string): TModel;
 declare const initializeGlobalContext: ({ Request, Response, Session }?: {
   Request?: any;
   Response?: any;
@@ -525,4 +680,4 @@ declare const abortIf: <T>(boolean: T, message?: string, code?: number) => asser
  */
 declare const assertFound: <T>(value: T | null | undefined, message: string, code?: number) => asserts value is T;
 //#endregion
-export { GlobalConfig as A, LoggerLog as B, DotPath as C, EnvRegistry as D, EnvLookup as E, HookPos as F, PublishConfirmation as G, MergedConfig as H, HookPositions as I, PublishGroup as J, PublishEntry as K, HookRegistry as L, HookArgs as M, HookFor as N, EnvReturn as O, HookName as P, IHook as R, ConfigShape as S, EnvKey as T, PaginationOptions as U, LoggerParseSignature as V, Primitive as W, Logger as X, UnionToIntersection as Y, ArkstackErrorPayload as _, abortIf as a, Choices as b, getModelSync as c, normalizePositiveInteger as d, perPage as f, AppConfig as g, Encryption as h, abort as i, GlobalEnv as j, FileImporter as k, initializeGlobalContext as l, Hash as m, ModelConstructor as n, assertFound as o, resolvePagination as p, PublishFilter as q, ModelRegistry as r, getModel as s, AbstractModelConstructor as t, isClass as u, ArkstackErrorShape as v, DotPathValue as w, ConfigRegistry as x, Choice as y, LoggerChalk as z };
+export { IHook as $, SerializedKeyPair as A, EnvKey as B, FingerprintOptions as C, NodeCipher as D, Keys as E, Choices as F, GlobalConfig as G, EnvRegistry as H, ConfigRegistry as I, HookFor as J, GlobalEnv as K, ConfigShape as L, ArkstackErrorPayload as M, ArkstackErrorShape as N, SealedBox as O, Choice as P, HookRegistry as Q, DotPath as R, EncryptionKey as S, KeyPair as T, EnvReturn as U, EnvLookup as V, FileImporter as W, HookPos as X, HookName as Y, HookPositions as Z, CipherOptions as _, abortIf as a, Primitive as at, DerivedKey as b, getModelSync as c, PublishFilter as ct, normalizePositiveInteger as d, Logger as dt, LoggerChalk as et, perPage as f, Cipher as g, ChannelOptions as h, abort as i, PaginationOptions as it, AppConfig as j, SecureChannel as k, initializeGlobalContext as l, PublishGroup as lt, Hash as m, ModelConstructor as n, LoggerParseSignature as nt, assertFound as o, PublishConfirmation as ot, resolvePagination as p, HookArgs as q, ModelRegistry as r, MergedConfig as rt, getModel$1 as s, PublishEntry as st, AbstractModelConstructor as t, LoggerLog as tt, isClass as u, UnionToIntersection as ut, Codec as v, KeyInput as w, Encryption as x, DeriveOptions as y, DotPathValue as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /// <reference path="./app.d.ts" />
-import { A as GlobalConfig, B as LoggerLog, C as DotPath, D as EnvRegistry, E as EnvLookup, F as HookPos, G as PublishConfirmation, H as MergedConfig, I as HookPositions, J as PublishGroup, K as PublishEntry, L as HookRegistry, M as HookArgs, N as HookFor, O as EnvReturn, P as HookName, R as IHook, S as ConfigShape, T as EnvKey, U as PaginationOptions, V as LoggerParseSignature, W as Primitive, X as Logger, Y as UnionToIntersection, _ as ArkstackErrorPayload, a as abortIf, b as Choices, c as getModelSync, d as normalizePositiveInteger, f as perPage, g as AppConfig, h as Encryption, i as abort, j as GlobalEnv, k as FileImporter, l as initializeGlobalContext, m as Hash, n as ModelConstructor, o as assertFound, p as resolvePagination, q as PublishFilter, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass, v as ArkstackErrorShape, w as DotPathValue, x as ConfigRegistry, y as Choice, z as LoggerChalk } from "./helpers-E_O2UDRn.js";
+import { $ as IHook, A as SerializedKeyPair, B as EnvKey, C as FingerprintOptions, D as NodeCipher, E as Keys, F as Choices, G as GlobalConfig, H as EnvRegistry, I as ConfigRegistry, J as HookFor, K as GlobalEnv, L as ConfigShape, M as ArkstackErrorPayload, N as ArkstackErrorShape, O as SealedBox, P as Choice, Q as HookRegistry, R as DotPath, S as EncryptionKey, T as KeyPair, U as EnvReturn, V as EnvLookup, W as FileImporter, X as HookPos, Y as HookName, Z as HookPositions, _ as CipherOptions, a as abortIf, at as Primitive, b as DerivedKey, c as getModelSync, ct as PublishFilter, d as normalizePositiveInteger, dt as Logger, et as LoggerChalk, f as perPage, g as Cipher, h as ChannelOptions, i as abort, it as PaginationOptions, j as AppConfig, k as SecureChannel, l as initializeGlobalContext, lt as PublishGroup, m as Hash, n as ModelConstructor, nt as LoggerParseSignature, o as assertFound, ot as PublishConfirmation, p as resolvePagination, q as HookArgs, r as ModelRegistry, rt as MergedConfig, s as getModel, st as PublishEntry, t as AbstractModelConstructor, tt as LoggerLog, u as isClass, ut as UnionToIntersection, v as Codec, w as KeyInput, x as Encryption, y as DeriveOptions, z as DotPathValue } from "./helpers-Bn-0uv3R.js";
 import { Arkstack } from "@arkstack/contract";
 import { ForkOptions } from "node:child_process";
 import pino from "pino";
@@ -514,4 +514,4 @@ declare const devServer: (options: DevServerRunnerOptions) => {
   closeWatcher(): Promise<void>;
 };
 //#endregion
-export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, Choice, Choices, ConfigLoader, ConfigRegistry, ConfigShape, DevServerRunnerOptions, DotPath, DotPathValue, Encryption, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, PaginationOptions, Primitive, PublishConfirmation, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devServer, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, type ChannelOptions, Choice, Choices, Cipher, type CipherOptions, Codec, ConfigLoader, ConfigRegistry, ConfigShape, type DeriveOptions, type DerivedKey, DevServerRunnerOptions, DotPath, DotPathValue, Encryption, EncryptionKey, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, type FingerprintOptions, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, type KeyInput, KeyPair, Keys, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, NodeCipher, PaginationOptions, Primitive, PublishConfirmation, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, SealedBox, SecureChannel, type SerializedKeyPair, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devServer, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { _ as EnvLoader, a as env, c as nodeEnv, d as resolveRuntimeDir, f as resolveRuntimeModule, g as configLoader, h as ConfigLoader, i as discoverCommands, l as outputDir, m as CONFIG_KEY, n as appUrl, o as importFile, p as toOutputPath, r as config, s as interopDefault, t as appKey, u as rebuildOutput, v as envLoader } from "./system-Die_Dv5y.js";
-import { _ as RequestException, b as Hash, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, l as assertFound, m as normalizePositiveInteger, p as isClass, s as abort, u as getModel, v as AppException, x as Encryption, y as Exception } from "./utils-mymPEYd4.js";
+import { C as Encryption, D as NodeCipher, E as Keys, O as SealedBox, S as Codec, T as KeyPair, _ as RequestException, b as Hash, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, k as SecureChannel, l as assertFound, m as normalizePositiveInteger, p as isClass, s as abort, u as getModel, v as AppException, w as EncryptionKey, x as Cipher, y as Exception } from "./utils-gKiLoXG9.js";
 import { Hook as Hook$1 } from "@arkstack/foundry";
 import { Arkstack } from "@arkstack/contract";
 import { str } from "@h3ravel/support";
@@ -660,4 +660,4 @@ const devServer = (options) => {
 	};
 };
 //#endregion
-export { AppException, CONFIG_KEY, ConfigLoader, Encryption, EnvLoader, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devServer, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+export { AppException, CONFIG_KEY, Cipher, Codec, ConfigLoader, Encryption, EncryptionKey, EnvLoader, ErrorHandler, Exception, Hash, Hook, KeyPair, Keys, Logger, NodeCipher, Publisher, RequestException, SealedBox, SecureChannel, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devServer, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { a as abortIf, c as getModelSync, d as normalizePositiveInteger, f as perPage, h as Encryption, i as abort, l as initializeGlobalContext, m as Hash, n as ModelConstructor, o as assertFound, p as resolvePagination, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass } from "../helpers-E_O2UDRn.js";
+import { A as SerializedKeyPair, C as FingerprintOptions, D as NodeCipher, E as Keys, O as SealedBox, S as EncryptionKey, T as KeyPair, _ as CipherOptions, a as abortIf, b as DerivedKey, c as getModelSync, d as normalizePositiveInteger, f as perPage, g as Cipher, h as ChannelOptions, i as abort, k as SecureChannel, l as initializeGlobalContext, m as Hash, n as ModelConstructor, o as assertFound, p as resolvePagination, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass, v as Codec, w as KeyInput, x as Encryption, y as DeriveOptions } from "../helpers-Bn-0uv3R.js";
 import { Model } from "arkormx";
 //#region src/utils/traits.d.ts
 declare const crc32: (str: string) => number;
@@ -184,4 +184,4 @@ type Derived<T extends (Trait | TypeFactory<Trait> | Cons)> = T extends TypeFact
  */
 declare function uses<T extends (Trait | TypeFactory<Trait> | Cons)>(instance: unknown, trait: T): instance is Derived<T>;
 //#endregion
-export { AbstractModelConstructor, Derived, Encryption, Hash, ModelConstructor, ModelRegistry, Trait, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, normalizePositiveInteger, perPage, resolvePagination, trait, use, uses };
+export { AbstractModelConstructor, type ChannelOptions, Cipher, type CipherOptions, Codec, type DeriveOptions, Derived, type DerivedKey, Encryption, EncryptionKey, type FingerprintOptions, Hash, type KeyInput, KeyPair, Keys, ModelConstructor, ModelRegistry, NodeCipher, SealedBox, SecureChannel, type SerializedKeyPair, Trait, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, normalizePositiveInteger, perPage, resolvePagination, trait, use, uses };

package/dist/utils/index.js

@@ -1,2 +1,2 @@
-import { a as use, b as Hash, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, i as trait, l as assertFound, m as normalizePositiveInteger, n as crc32, o as uses, p as isClass, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, x as Encryption } from "../utils-mymPEYd4.js";
-export { Encryption, Hash, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, normalizePositiveInteger, perPage, resolvePagination, trait, use, uses };
+import { C as Encryption, D as NodeCipher, E as Keys, O as SealedBox, S as Codec, T as KeyPair, a as use, b as Hash, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, i as trait, k as SecureChannel, l as assertFound, m as normalizePositiveInteger, n as crc32, o as uses, p as isClass, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, w as EncryptionKey, x as Cipher } from "../utils-gKiLoXG9.js";
+export { Cipher, Codec, Encryption, EncryptionKey, Hash, KeyPair, Keys, NodeCipher, SealedBox, SecureChannel, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, normalizePositiveInteger, perPage, resolvePagination, trait, use, uses };

package/dist/{utils-mymPEYd4.js → utils-gKiLoXG9.js}

@@ -1,34 +1,201 @@
-import { a as env, f as resolveRuntimeModule, o as importFile, t as appKey } from "./system-Die_Dv5y.js";
-import { createRequire } from "node:module";
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-import { Arkstack } from "@arkstack/contract";
-import path from "node:path";
+import { a as env, t as appKey } from "./system-Die_Dv5y.js";
+import { Cipher, Codec, EncryptionKey, KeyPair, Keys, SealedBox, SecureChannel } from "@arkstack/encryption";
+import { NodeCipher } from "@arkstack/encryption/node";
 import { Secret, TOTP } from "otpauth";
 import { compare, genSalt, hash } from "bcryptjs";
+import { getModel } from "arkormx";
 //#region src/utils/encryption.ts
+/**
+* Application facing encryption, bound to the app key.
+*
+* This is a thin wrapper over `@arkstack/encryption`. `encrypt()` and
+* `decrypt()` keep the synchronous signatures and the exact payload format
+* they have always had — `<iv>:<authTag>:<ciphertext>`, AES-256-GCM under
+* SHA-256 of `APP_KEY` — so existing ciphertexts and call sites are unaffected.
+*
+* Everything else is new surface: the asynchronous methods run on the Web
+* Crypto API, which means a browser holding the same key (or the same key pair
+* peer) can decrypt what the server wrote, and the server can decrypt what the
+* browser wrote.
+*/
 var Encryption = class {
-	static algorithm = "aes-256-gcm";
-	static getKey() {
+	/**
+	* Encrypt a string with the application key.
+	*
+	* @param value
+	* @param key Override the application key for this call.
+	* @returns
+	*/
+	static encrypt(value, key) {
+		return NodeCipher.encrypt(value, this.material(key));
+	}
+	/**
+	* Decrypt a payload produced by {@link encrypt}.
+	*
+	* @param payload
+	* @param key Override the application key for this call.
+	* @returns
+	*/
+	static decrypt(payload, key) {
+		return NodeCipher.decrypt(payload, this.material(key));
+	}
+	/**
+	* Encrypt through the isomorphic Web Crypto implementation.
+	*
+	* Produces the same payload format as {@link encrypt}; use it when the
+	* calling code is (or may become) shared with the browser.
+	*
+	* @param value
+	* @param key
+	* @param options
+	* @returns
+	*/
+	static async encryptAsync(value, key, options = {}) {
+		return await (await this.cipher(key)).encrypt(value, options);
+	}
+	/**
+	* Decrypt through the isomorphic Web Crypto implementation.
+	*
+	* @param payload
+	* @param key
+	* @param options
+	* @returns
+	*/
+	static async decryptAsync(payload, key, options = {}) {
+		return await (await this.cipher(key)).decrypt(payload, options);
+	}
+	/**
+	* A cipher bound to the application key, for encrypting many values or raw
+	* bytes without re-deriving the key each time.
+	*
+	* @param key
+	* @returns
+	*/
+	static async cipher(key) {
+		return key === void 0 ? new Cipher(new EncryptionKey(this.material())) : await Cipher.from(key);
+	}
+	/**
+	* The application key as it appears in the environment.
+	*
+	* Reads `APP_KEY`, falling back to the legacy `TWO_FACTOR_ENCRYPTION_KEY`
+	* variable. Override this in a subclass to source the key elsewhere.
+	*
+	* @returns
+	*/
+	static secret() {
 		const secret = appKey("TWO_FACTOR_ENCRYPTION_KEY");
-		if (!secret) throw new Error("APP_KEY is required to use two-factor authentication. Run `ark key:generate`.");
-		return createHash("sha256").update(secret).digest();
-	}
-	static encrypt(value) {
-		const iv = randomBytes(12);
-		const cipher = createCipheriv(this.algorithm, this.getKey(), iv);
-		const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
-		return [
-			iv,
-			cipher.getAuthTag(),
-			ciphertext
-		].map((part) => part.toString("base64url")).join(":");
-	}
-	static decrypt(payload) {
-		const [iv, authTag, ciphertext] = payload.split(":");
-		if (!iv || !authTag || !ciphertext) throw new Error("Invalid encrypted payload format");
-		const decipher = createDecipheriv(this.algorithm, this.getKey(), Buffer.from(iv, "base64url"));
-		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
-		return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64url")), decipher.final()]).toString("utf8");
+		if (!secret) throw new Error("APP_KEY is required to use Encryption. Run `ark key:generate`.");
+		return secret;
+	}
+	/**
+	* The 32 bytes of key material actually handed to the cipher: SHA-256 of
+	* the application key, or of an explicit override.
+	*
+	* The same bytes are reachable in the browser with
+	* `EncryptionKey.fromSecret(secret)`.
+	*
+	* @param key
+	* @returns
+	*/
+	static material(key) {
+		if (key === void 0) return NodeCipher.fromSecret(this.secret());
+		if (key instanceof EncryptionKey) return key.bytes;
+		if (key instanceof Uint8Array) return key;
+		if (typeof key === "string") return NodeCipher.resolve(key);
+		throw new TypeError("A CryptoKey cannot be used with the synchronous cipher; pass raw key material instead");
+	}
+	/**
+	* Generate a random base64url encryption key.
+	*
+	* @param length Key length in bytes, defaults to 32.
+	* @returns
+	*/
+	static generateKey(length = 32) {
+		return Keys.generateString(length);
+	}
+	/**
+	* Generate an end-to-end encryption identity. The public key is published,
+	* the private key stays with its owner.
+	*
+	* @returns
+	*/
+	static async generateKeyPair() {
+		return await Keys.generateSerializedPair();
+	}
+	/**
+	* Stretch a user supplied password into a key with PBKDF2-HMAC-SHA256.
+	*
+	* @param password
+	* @param options
+	* @returns
+	*/
+	static async deriveKey(password, options = {}) {
+		return await Keys.derive(password, options);
+	}
+	/**
+	* Constant time comparison of two keys.
+	*
+	* @param left
+	* @param right
+	* @returns
+	*/
+	static compareKeys(left, right) {
+		return Keys.matches(left, right);
+	}
+	/**
+	* A displayable digest of a key, safe to show to users or write to logs.
+	*
+	* @param key Defaults to the application key.
+	* @param options
+	* @returns
+	*/
+	static async fingerprint(key, options = {}) {
+		return await Keys.fingerprint(key ?? this.material(), options);
+	}
+	/**
+	* Open an end-to-end encrypted channel between a local private key and a
+	* peer's public key. Neither key, nor the secret they agree on, ever
+	* crosses the wire.
+	*
+	* @param privateKey
+	* @param peerPublicKey
+	* @param options
+	* @returns
+	*/
+	static async channel(privateKey, peerPublicKey, options = {}) {
+		return await SecureChannel.between(privateKey, peerPublicKey, options);
+	}
+	/**
+	* Encrypt a message to a public key without needing a sender identity.
+	*
+	* @param message
+	* @param recipientPublicKey
+	* @returns
+	*/
+	static async seal(message, recipientPublicKey) {
+		return await SealedBox.seal(message, recipientPublicKey);
+	}
+	/**
+	* Open a payload produced by {@link seal}.
+	*
+	* @param payload
+	* @param recipientPrivateKey
+	* @returns
+	*/
+	static async open(payload, recipientPrivateKey) {
+		return await SealedBox.open(payload, recipientPrivateKey);
+	}
+	/**
+	* The safety number for a conversation between two public keys — show it to
+	* both participants so they can verify nobody swapped a key in transit.
+	*
+	* @param first
+	* @param second
+	* @param groups
+	* @returns
+	*/
+	static async safetyNumber(first, second, groups = 12) {
+		return await Keys.safetyNumber(first, second, groups);
 	}
 };
 //#endregion
@@ -202,37 +369,11 @@ const resolvePagination = (query, defaults) => {
 		perPage: perPage(query, defaults)
 	};
 };
-async function getModel(modelName) {
-	const resolveModelExport = (module, modelName) => {
-		if (!isModelModule(module)) return module;
-		return module.default ?? module[modelName] ?? module;
-	};
-	const isModelModule = (value) => typeof value === "object" && value !== null;
-	const { getUserConfig } = await import("arkormx");
-	const modelPath = getUserConfig().paths?.models || "./src/models";
-	const sourcePath = path.join(path.isAbsolute(modelPath) ? modelPath : path.join(Arkstack.rootDir(), modelPath), modelName);
-	const modulePath = resolveRuntimeModule(sourcePath);
-	const model = resolveModelExport(await importFile(modulePath), path.basename(modelName, path.extname(modelName)));
-	if (typeof model !== "function") throw new Error(`Model "${modelName}" not found`);
-	return model;
+function getModel$1(modelName) {
+	return getModel(modelName);
 }
-const isModelModule = (value) => typeof value === "object" && value !== null;
-const resolveModelExport = (module, modelName) => {
-	if (!isModelModule(module)) return module;
-	return module.default ?? module[modelName] ?? module;
-};
 function getModelSync(modelName) {
-	const require = createRequire(import.meta.url);
-	const { Arkorm, getUserConfig } = require("arkormx");
-	const exportName = path.basename(modelName, path.extname(modelName));
-	const registeredModel = Arkorm.getRegisteredModels().find((model) => model.name === exportName);
-	if (registeredModel) return registeredModel;
-	const modelPath = getUserConfig().paths?.models || "./src/models";
-	const sourcePath = path.join(path.isAbsolute(modelPath) ? modelPath : path.join(Arkstack.rootDir(), modelPath), modelName);
-	const module = require(resolveRuntimeModule(sourcePath));
-	const model = resolveModelExport(module, exportName);
-	if (typeof model !== "function") throw new Error(`Model "${modelName}" not found`);
-	return model;
+	return getModel(modelName);
 }
 const initializeGlobalContext = async ({ Request, Response, Session } = {}) => {
 	try {
@@ -492,4 +633,4 @@ function uses(instance, trait) {
 	return false;
 }
 //#endregion
-export { RequestException as _, use as a, Hash as b, abortIf as c, getModelSync as d, initializeGlobalContext as f, resolvePagination as g, perPage as h, trait as i, assertFound as l, normalizePositiveInteger as m, crc32 as n, uses as o, isClass as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, AppException as v, Encryption as x, Exception as y };
+export { Encryption as C, NodeCipher as D, Keys as E, SealedBox as O, Codec as S, KeyPair as T, RequestException as _, use as a, Hash as b, abortIf as c, getModelSync as d, initializeGlobalContext as f, resolvePagination as g, perPage as h, trait as i, SecureChannel as k, assertFound as l, normalizePositiveInteger as m, crc32 as n, uses as o, isClass as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel$1 as u, AppException as v, EncryptionKey as w, Cipher as x, Exception as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.17.26",
+  "version": "0.18.1",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -42,13 +42,14 @@
     "jiti": "^2.7.0",
     "otpauth": "^9.5.1",
     "pino": "^10.3.1",
-    "selfsigned": "^2.4.1"
+    "selfsigned": "^2.4.1",
+    "@arkstack/encryption": "^0.18.1"
   },
   "peerDependencies": {
     "@h3ravel/support": "^2.2.7",
     "arkormx": "^2.12.8",
-    "@arkstack/contract": "^0.17.26",
-    "@arkstack/foundry": "^0.17.26"
+    "@arkstack/contract": "^0.18.1",
+    "@arkstack/foundry": "^0.18.1"
   },
   "optionalDependencies": {
     "@faker-js/faker": "^10.4.0"