@aglyn/shared-util-tools 1.0.0-beta.143

package/src/lib/secret-box.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A SECRET BOX: a short secret sealed at rest with AES-256-GCM.
+ *
+ * For a value the platform must be able to read back — a provider refresh
+ * token, a webhook signing key — and must never store in the clear. Hashing
+ * is the right tool for a secret that is only ever COMPARED (an API key);
+ * this is for one that is USED.
+ *
+ * ## Server-only, and never on the barrel
+ *
+ * It imports `node:crypto`, so it is reached by its own subpath —
+ * `@aglyn/shared-util-tools/secret-box` — and the library index does not
+ * re-export it. A browser bundle that pulled this in would fail to build,
+ * and one that did not fail would be shipping key handling to a page.
+ *
+ * It reads no environment. The caller resolves its key material from wherever
+ * that caller's credential lives and hands it in, so which process may hold a
+ * key is decided by the caller's location, not by this module.
+ *
+ * ## The sealed form
+ *
+ *     sb1.<keyId>.<iv>.<ciphertext>.<tag>
+ *
+ * Each part after the key id is base64url. The IV is 12 random bytes per seal
+ * and the tag is GCM's full 16 bytes. The version and the key id are bound
+ * into the tag as additional authenticated data, so neither can be rewritten
+ * to make a sealed value open under a different key or scheme.
+ *
+ * ## Context
+ *
+ * A caller may bind a sealed value to where it belongs — a document path, a
+ * purpose — by passing the same `context` to seal and open. The context is
+ * authenticated, never stored, so a value copied from one record into another
+ * refuses to open there, even under the right key.
+ *
+ * ## Rotation
+ *
+ * A key carries an id, and a sealed value names the id it was sealed under. A
+ * keyring holds the current key, which seals, and any number of earlier keys,
+ * which only open. Rotating is: put the new key first, keep the old one after
+ * it until nothing sealed under it remains, then drop it. {@link openSecret}
+ * reports which key opened a value, so a reader can reseal under the current
+ * key as it goes ({@link needsReseal}).
+ *
+ * ## Refusals
+ *
+ * Every failure throws {@link SecretBoxError} with a stable code and a message
+ * that never contains the plaintext, the ciphertext or key material.
+ * Authentication failure is one code, `refused`, whether the ciphertext was
+ * altered, the key is wrong or the context differs: GCM cannot tell those
+ * apart, and a caller has no business treating them differently.
+ */
+/** The version tag every sealed value starts with. */
+export declare const SECRET_BOX_VERSION = "sb1";
+/** Bytes of key material: AES-256. */
+export declare const SECRET_BOX_KEY_BYTES = 32;
+/** Why a key could not be parsed or a value could not be sealed or opened. */
+export type SecretBoxErrorCode = 
+/** Key material that is not 32 bytes of base64, or an unusable key id. */
+'invalid-key'
+/** Not a sealed value at all: wrong shape, bad encoding, wrong lengths. */
+ | 'malformed'
+/** A sealed value from a scheme version this module does not open. */
+ | 'unsupported-version'
+/** Sealed under a key id the keyring does not hold. */
+ | 'unknown-key'
+/** Authentication failed: altered, wrong key, or a different context. */
+ | 'refused';
+export declare class SecretBoxError extends Error {
+    readonly code: SecretBoxErrorCode;
+    constructor(code: SecretBoxErrorCode, message: string);
+}
+/** One key: its id and its 32 bytes. */
+export interface SecretBoxKey {
+    readonly id: string;
+    readonly material: Uint8Array;
+}
+/**
+ * The keys a reader holds. `current` seals; every entry of `keys` — `current`
+ * included, first — opens.
+ */
+export interface SecretBoxKeyring {
+    readonly current: SecretBoxKey;
+    readonly keys: readonly SecretBoxKey[];
+}
+/** What opening a sealed value produced. */
+export interface OpenedSecret {
+    readonly plaintext: string;
+    /** The id of the key that opened it. */
+    readonly keyId: string;
+}
+/**
+ * The id a key is known by when none is given: eight characters derived from
+ * the key itself with HMAC, so it names the key without being a hash of it
+ * anyone could test a guess against.
+ */
+export declare function deriveSecretBoxKeyId(material: Uint8Array): string;
+/**
+ * A key from base64 material (standard or URL-safe), with an explicit id or
+ * the derived one.
+ */
+export declare function createSecretBoxKey(material: Uint8Array | string, id?: string): SecretBoxKey;
+/**
+ * A keyring from one configuration value: keys separated by commas or
+ * whitespace, the first the current one. Each entry is base64 material, or
+ * `id:material` to name it explicitly.
+ *
+ * Refuses an empty value, any unparseable entry and two entries with one id —
+ * a reader could not know which of the two a sealed value meant.
+ */
+export declare function parseSecretBoxKeyring(value: string): SecretBoxKeyring;
+/**
+ * Seals a string under a key.
+ *
+ * `context` is bound into the tag, and the same value must be passed to
+ * {@link openSecret}. `iv` is a test seam for a deterministic IV; never pass
+ * one in production, because a repeated IV under one key breaks GCM entirely.
+ */
+export declare function sealSecret(plaintext: string, key: SecretBoxKey, options?: {
+    context?: string;
+    iv?: Uint8Array;
+}): string;
+/**
+ * Opens a sealed value with whichever key in the ring it names.
+ *
+ * Throws {@link SecretBoxError}: `malformed` for anything not shaped like a
+ * sealed value, `unsupported-version`, `unknown-key` when the ring has no key
+ * by that id, and `refused` when authentication fails.
+ */
+export declare function openSecret(sealed: string, keys: SecretBoxKeyring | SecretBoxKey | readonly SecretBoxKey[], options?: {
+    context?: string;
+}): OpenedSecret;
+/** Whether a value opened under an earlier key and should be sealed again. */
+export declare function needsReseal(opened: OpenedSecret, keyring: SecretBoxKeyring): boolean;
+/** The id of the key a sealed value names, or `null` when it is not one. */
+export declare function sealedSecretKeyId(sealed: unknown): string | null;

package/src/lib/secret-box.js

@@ -0,0 +1,263 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
+/**
+ * A SECRET BOX: a short secret sealed at rest with AES-256-GCM.
+ *
+ * For a value the platform must be able to read back — a provider refresh
+ * token, a webhook signing key — and must never store in the clear. Hashing
+ * is the right tool for a secret that is only ever COMPARED (an API key);
+ * this is for one that is USED.
+ *
+ * ## Server-only, and never on the barrel
+ *
+ * It imports `node:crypto`, so it is reached by its own subpath —
+ * `@aglyn/shared-util-tools/secret-box` — and the library index does not
+ * re-export it. A browser bundle that pulled this in would fail to build,
+ * and one that did not fail would be shipping key handling to a page.
+ *
+ * It reads no environment. The caller resolves its key material from wherever
+ * that caller's credential lives and hands it in, so which process may hold a
+ * key is decided by the caller's location, not by this module.
+ *
+ * ## The sealed form
+ *
+ *     sb1.<keyId>.<iv>.<ciphertext>.<tag>
+ *
+ * Each part after the key id is base64url. The IV is 12 random bytes per seal
+ * and the tag is GCM's full 16 bytes. The version and the key id are bound
+ * into the tag as additional authenticated data, so neither can be rewritten
+ * to make a sealed value open under a different key or scheme.
+ *
+ * ## Context
+ *
+ * A caller may bind a sealed value to where it belongs — a document path, a
+ * purpose — by passing the same `context` to seal and open. The context is
+ * authenticated, never stored, so a value copied from one record into another
+ * refuses to open there, even under the right key.
+ *
+ * ## Rotation
+ *
+ * A key carries an id, and a sealed value names the id it was sealed under. A
+ * keyring holds the current key, which seals, and any number of earlier keys,
+ * which only open. Rotating is: put the new key first, keep the old one after
+ * it until nothing sealed under it remains, then drop it. {@link openSecret}
+ * reports which key opened a value, so a reader can reseal under the current
+ * key as it goes ({@link needsReseal}).
+ *
+ * ## Refusals
+ *
+ * Every failure throws {@link SecretBoxError} with a stable code and a message
+ * that never contains the plaintext, the ciphertext or key material.
+ * Authentication failure is one code, `refused`, whether the ciphertext was
+ * altered, the key is wrong or the context differs: GCM cannot tell those
+ * apart, and a caller has no business treating them differently.
+ */ /** The version tag every sealed value starts with. */ export const SECRET_BOX_VERSION = 'sb1';
+/** Bytes of key material: AES-256. */ export const SECRET_BOX_KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const ALGORITHM = 'aes-256-gcm';
+/** A key id: short, URL-safe and free of the separator. */ const KEY_ID = /^[A-Za-z0-9_-]{1,32}$/;
+/** Standard or URL-safe base64, padded or not. */ const BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/;
+/** Unpadded base64url, the only alphabet a sealed value uses. */ const BASE64URL = /^[A-Za-z0-9_-]+$/;
+export class SecretBoxError extends Error {
+    constructor(code, message){
+        super(message);
+        this.name = 'SecretBoxError';
+        this.code = code;
+    }
+}
+const toBase64Url = (bytes)=>Buffer.from(bytes).toString('base64url');
+function decodeBase64Url(part, expectedBytes) {
+    if (!BASE64URL.test(part)) {
+        throw new SecretBoxError('malformed', 'The sealed value is not valid base64url.');
+    }
+    const bytes = Buffer.from(part, 'base64url');
+    // Re-encoding catches a part with trailing bits Node's decoder silently
+    // dropped, which would otherwise be two spellings of one value.
+    if (toBase64Url(bytes) !== part) {
+        throw new SecretBoxError('malformed', 'The sealed value is not canonical base64url.');
+    }
+    if (expectedBytes !== undefined && bytes.length !== expectedBytes) {
+        throw new SecretBoxError('malformed', 'A part of the sealed value has the wrong length.');
+    }
+    return bytes;
+}
+/**
+ * The id a key is known by when none is given: eight characters derived from
+ * the key itself with HMAC, so it names the key without being a hash of it
+ * anyone could test a guess against.
+ */ export function deriveSecretBoxKeyId(material) {
+    return createHmac('sha256', Buffer.from(material)).update('secret-box:key-id').digest().subarray(0, 6).toString('base64url');
+}
+/**
+ * A key from base64 material (standard or URL-safe), with an explicit id or
+ * the derived one.
+ */ export function createSecretBoxKey(material, id) {
+    let bytes;
+    if (typeof material === 'string') {
+        const trimmed = material.trim();
+        if (!BASE64.test(trimmed)) {
+            throw new SecretBoxError('invalid-key', 'A secret box key must be base64.');
+        }
+        bytes = Buffer.from(trimmed.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+    } else {
+        bytes = Buffer.from(material);
+    }
+    if (bytes.length !== SECRET_BOX_KEY_BYTES) {
+        throw new SecretBoxError('invalid-key', `A secret box key must be ${SECRET_BOX_KEY_BYTES} bytes.`);
+    }
+    const keyId = id != null ? id : deriveSecretBoxKeyId(bytes);
+    if (!KEY_ID.test(keyId)) {
+        throw new SecretBoxError('invalid-key', 'A secret box key id must be 1-32 letters, digits, "-" or "_".');
+    }
+    return {
+        id: keyId,
+        material: bytes
+    };
+}
+/**
+ * A keyring from one configuration value: keys separated by commas or
+ * whitespace, the first the current one. Each entry is base64 material, or
+ * `id:material` to name it explicitly.
+ *
+ * Refuses an empty value, any unparseable entry and two entries with one id —
+ * a reader could not know which of the two a sealed value meant.
+ */ export function parseSecretBoxKeyring(value) {
+    const entries = String(value != null ? value : '').split(/[\s,]+/).map((entry)=>entry.trim()).filter(Boolean);
+    if (!entries.length) {
+        throw new SecretBoxError('invalid-key', 'No secret box key was given.');
+    }
+    const keys = entries.map((entry)=>{
+        const separator = entry.indexOf(':');
+        return separator > 0 ? createSecretBoxKey(entry.slice(separator + 1), entry.slice(0, separator)) : createSecretBoxKey(entry);
+    });
+    const ids = new Set();
+    for (const key of keys){
+        if (ids.has(key.id)) {
+            throw new SecretBoxError('invalid-key', 'Two secret box keys share one id.');
+        }
+        ids.add(key.id);
+    }
+    return {
+        current: keys[0],
+        keys
+    };
+}
+function asKeyring(keys) {
+    if (Array.isArray(keys)) return keys;
+    if ('current' in keys) {
+        return keys.keys;
+    }
+    return [
+        keys
+    ];
+}
+/** Version and key id, then the caller's context, as authenticated data. */ function additionalData(keyId, context) {
+    return Buffer.from(`${SECRET_BOX_VERSION}\u0000${keyId}\u0000${context != null ? context : ''}`, 'utf8');
+}
+/**
+ * Seals a string under a key.
+ *
+ * `context` is bound into the tag, and the same value must be passed to
+ * {@link openSecret}. `iv` is a test seam for a deterministic IV; never pass
+ * one in production, because a repeated IV under one key breaks GCM entirely.
+ */ export function sealSecret(plaintext, key, options = {}) {
+    var _key_material;
+    if (typeof plaintext !== 'string') {
+        throw new SecretBoxError('malformed', 'Only a string can be sealed.');
+    }
+    if (!key || ((_key_material = key.material) == null ? void 0 : _key_material.length) !== SECRET_BOX_KEY_BYTES || !KEY_ID.test(key.id)) {
+        throw new SecretBoxError('invalid-key', 'The sealing key is not a usable secret box key.');
+    }
+    const iv = options.iv ? Buffer.from(options.iv) : randomBytes(IV_BYTES);
+    if (iv.length !== IV_BYTES) {
+        throw new SecretBoxError('malformed', `A secret box IV must be ${IV_BYTES} bytes.`);
+    }
+    const cipher = createCipheriv(ALGORITHM, Buffer.from(key.material), iv, {
+        authTagLength: TAG_BYTES
+    });
+    cipher.setAAD(additionalData(key.id, options.context));
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    return [
+        SECRET_BOX_VERSION,
+        key.id,
+        toBase64Url(iv),
+        toBase64Url(ciphertext),
+        toBase64Url(tag)
+    ].join('.');
+}
+/**
+ * Opens a sealed value with whichever key in the ring it names.
+ *
+ * Throws {@link SecretBoxError}: `malformed` for anything not shaped like a
+ * sealed value, `unsupported-version`, `unknown-key` when the ring has no key
+ * by that id, and `refused` when authentication fails.
+ */ export function openSecret(sealed, keys, options = {}) {
+    if (typeof sealed !== 'string' || !sealed) {
+        throw new SecretBoxError('malformed', 'The sealed value is empty.');
+    }
+    const parts = sealed.split('.');
+    if (parts.length !== 5) {
+        throw new SecretBoxError('malformed', 'The sealed value does not have five parts.');
+    }
+    const [version, keyId, ivPart, ciphertextPart, tagPart] = parts;
+    if (version !== SECRET_BOX_VERSION) {
+        throw new SecretBoxError('unsupported-version', 'The sealed value was made by a scheme this reader does not open.');
+    }
+    if (!KEY_ID.test(keyId)) {
+        throw new SecretBoxError('malformed', 'The sealed value names an unusable key id.');
+    }
+    const iv = decodeBase64Url(ivPart, IV_BYTES);
+    // An empty ciphertext is a sealed empty string, and legitimate.
+    const ciphertext = ciphertextPart ? decodeBase64Url(ciphertextPart) : Buffer.alloc(0);
+    const tag = decodeBase64Url(tagPart, TAG_BYTES);
+    const key = asKeyring(keys).find((candidate)=>candidate.id === keyId);
+    if (!key) {
+        throw new SecretBoxError('unknown-key', 'The sealed value was sealed under a key this reader does not hold.');
+    }
+    try {
+        const decipher = createDecipheriv(ALGORITHM, Buffer.from(key.material), iv, {
+            authTagLength: TAG_BYTES
+        });
+        decipher.setAAD(additionalData(keyId, options.context));
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final()
+        ]).toString('utf8');
+        return {
+            plaintext,
+            keyId
+        };
+    } catch (unused) {
+        throw new SecretBoxError('refused', 'The sealed value did not authenticate: it was altered, or the key or context is wrong.');
+    }
+}
+/** Whether a value opened under an earlier key and should be sealed again. */ export function needsReseal(opened, keyring) {
+    return opened.keyId !== keyring.current.id;
+}
+/** The id of the key a sealed value names, or `null` when it is not one. */ export function sealedSecretKeyId(sealed) {
+    if (typeof sealed !== 'string') return null;
+    const parts = sealed.split('.');
+    return parts.length === 5 && parts[0] === SECRET_BOX_VERSION && KEY_ID.test(parts[1]) ? parts[1] : null;
+}
+
+//# sourceMappingURL=secret-box.js.map

package/src/lib/secret-box.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/tools/src/lib/secret-box.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  createCipheriv,\n  createDecipheriv,\n  createHmac,\n  randomBytes,\n} from 'node:crypto'\n\n/**\n * A SECRET BOX: a short secret sealed at rest with AES-256-GCM.\n *\n * For a value the platform must be able to read back — a provider refresh\n * token, a webhook signing key — and must never store in the clear. Hashing\n * is the right tool for a secret that is only ever COMPARED (an API key);\n * this is for one that is USED.\n *\n * ## Server-only, and never on the barrel\n *\n * It imports `node:crypto`, so it is reached by its own subpath —\n * `@aglyn/shared-util-tools/secret-box` — and the library index does not\n * re-export it. A browser bundle that pulled this in would fail to build,\n * and one that did not fail would be shipping key handling to a page.\n *\n * It reads no environment. The caller resolves its key material from wherever\n * that caller's credential lives and hands it in, so which process may hold a\n * key is decided by the caller's location, not by this module.\n *\n * ## The sealed form\n *\n *     sb1.<keyId>.<iv>.<ciphertext>.<tag>\n *\n * Each part after the key id is base64url. The IV is 12 random bytes per seal\n * and the tag is GCM's full 16 bytes. The version and the key id are bound\n * into the tag as additional authenticated data, so neither can be rewritten\n * to make a sealed value open under a different key or scheme.\n *\n * ## Context\n *\n * A caller may bind a sealed value to where it belongs — a document path, a\n * purpose — by passing the same `context` to seal and open. The context is\n * authenticated, never stored, so a value copied from one record into another\n * refuses to open there, even under the right key.\n *\n * ## Rotation\n *\n * A key carries an id, and a sealed value names the id it was sealed under. A\n * keyring holds the current key, which seals, and any number of earlier keys,\n * which only open. Rotating is: put the new key first, keep the old one after\n * it until nothing sealed under it remains, then drop it. {@link openSecret}\n * reports which key opened a value, so a reader can reseal under the current\n * key as it goes ({@link needsReseal}).\n *\n * ## Refusals\n *\n * Every failure throws {@link SecretBoxError} with a stable code and a message\n * that never contains the plaintext, the ciphertext or key material.\n * Authentication failure is one code, `refused`, whether the ciphertext was\n * altered, the key is wrong or the context differs: GCM cannot tell those\n * apart, and a caller has no business treating them differently.\n */\n\n/** The version tag every sealed value starts with. */\nexport const SECRET_BOX_VERSION = 'sb1'\n\n/** Bytes of key material: AES-256. */\nexport const SECRET_BOX_KEY_BYTES = 32\n\nconst IV_BYTES = 12\nconst TAG_BYTES = 16\nconst ALGORITHM = 'aes-256-gcm'\n\n/** A key id: short, URL-safe and free of the separator. */\nconst KEY_ID = /^[A-Za-z0-9_-]{1,32}$/\n\n/** Standard or URL-safe base64, padded or not. */\nconst BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/\n\n/** Unpadded base64url, the only alphabet a sealed value uses. */\nconst BASE64URL = /^[A-Za-z0-9_-]+$/\n\n/** Why a key could not be parsed or a value could not be sealed or opened. */\nexport type SecretBoxErrorCode =\n  /** Key material that is not 32 bytes of base64, or an unusable key id. */\n  | 'invalid-key'\n  /** Not a sealed value at all: wrong shape, bad encoding, wrong lengths. */\n  | 'malformed'\n  /** A sealed value from a scheme version this module does not open. */\n  | 'unsupported-version'\n  /** Sealed under a key id the keyring does not hold. */\n  | 'unknown-key'\n  /** Authentication failed: altered, wrong key, or a different context. */\n  | 'refused'\n\nexport class SecretBoxError extends Error {\n  readonly code: SecretBoxErrorCode\n\n  constructor(code: SecretBoxErrorCode, message: string) {\n    super(message)\n    this.name = 'SecretBoxError'\n    this.code = code\n  }\n}\n\n/** One key: its id and its 32 bytes. */\nexport interface SecretBoxKey {\n  readonly id: string\n  readonly material: Uint8Array\n}\n\n/**\n * The keys a reader holds. `current` seals; every entry of `keys` — `current`\n * included, first — opens.\n */\nexport interface SecretBoxKeyring {\n  readonly current: SecretBoxKey\n  readonly keys: readonly SecretBoxKey[]\n}\n\n/** What opening a sealed value produced. */\nexport interface OpenedSecret {\n  readonly plaintext: string\n  /** The id of the key that opened it. */\n  readonly keyId: string\n}\n\nconst toBase64Url = (bytes: Uint8Array): string =>\n  Buffer.from(bytes).toString('base64url')\n\nfunction decodeBase64Url(part: string, expectedBytes?: number): Buffer {\n  if (!BASE64URL.test(part)) {\n    throw new SecretBoxError('malformed', 'The sealed value is not valid base64url.')\n  }\n  const bytes = Buffer.from(part, 'base64url')\n  // Re-encoding catches a part with trailing bits Node's decoder silently\n  // dropped, which would otherwise be two spellings of one value.\n  if (toBase64Url(bytes) !== part) {\n    throw new SecretBoxError('malformed', 'The sealed value is not canonical base64url.')\n  }\n  if (expectedBytes !== undefined && bytes.length !== expectedBytes) {\n    throw new SecretBoxError('malformed', 'A part of the sealed value has the wrong length.')\n  }\n  return bytes\n}\n\n/**\n * The id a key is known by when none is given: eight characters derived from\n * the key itself with HMAC, so it names the key without being a hash of it\n * anyone could test a guess against.\n */\nexport function deriveSecretBoxKeyId(material: Uint8Array): string {\n  return createHmac('sha256', Buffer.from(material))\n    .update('secret-box:key-id')\n    .digest()\n    .subarray(0, 6)\n    .toString('base64url')\n}\n\n/**\n * A key from base64 material (standard or URL-safe), with an explicit id or\n * the derived one.\n */\nexport function createSecretBoxKey(\n  material: Uint8Array | string,\n  id?: string,\n): SecretBoxKey {\n  let bytes: Buffer\n  if (typeof material === 'string') {\n    const trimmed = material.trim()\n    if (!BASE64.test(trimmed)) {\n      throw new SecretBoxError('invalid-key', 'A secret box key must be base64.')\n    }\n    bytes = Buffer.from(trimmed.replace(/-/g, '+').replace(/_/g, '/'), 'base64')\n  } else {\n    bytes = Buffer.from(material)\n  }\n  if (bytes.length !== SECRET_BOX_KEY_BYTES) {\n    throw new SecretBoxError(\n      'invalid-key',\n      `A secret box key must be ${SECRET_BOX_KEY_BYTES} bytes.`,\n    )\n  }\n  const keyId = id ?? deriveSecretBoxKeyId(bytes)\n  if (!KEY_ID.test(keyId)) {\n    throw new SecretBoxError(\n      'invalid-key',\n      'A secret box key id must be 1-32 letters, digits, \"-\" or \"_\".',\n    )\n  }\n  return { id: keyId, material: bytes }\n}\n\n/**\n * A keyring from one configuration value: keys separated by commas or\n * whitespace, the first the current one. Each entry is base64 material, or\n * `id:material` to name it explicitly.\n *\n * Refuses an empty value, any unparseable entry and two entries with one id —\n * a reader could not know which of the two a sealed value meant.\n */\nexport function parseSecretBoxKeyring(value: string): SecretBoxKeyring {\n  const entries = String(value ?? '')\n    .split(/[\\s,]+/)\n    .map((entry) => entry.trim())\n    .filter(Boolean)\n  if (!entries.length) {\n    throw new SecretBoxError('invalid-key', 'No secret box key was given.')\n  }\n  const keys = entries.map((entry) => {\n    const separator = entry.indexOf(':')\n    return separator > 0\n      ? createSecretBoxKey(entry.slice(separator + 1), entry.slice(0, separator))\n      : createSecretBoxKey(entry)\n  })\n  const ids = new Set<string>()\n  for (const key of keys) {\n    if (ids.has(key.id)) {\n      throw new SecretBoxError('invalid-key', 'Two secret box keys share one id.')\n    }\n    ids.add(key.id)\n  }\n  return { current: keys[0], keys }\n}\n\nfunction asKeyring(\n  keys: SecretBoxKeyring | SecretBoxKey | readonly SecretBoxKey[],\n): readonly SecretBoxKey[] {\n  if (Array.isArray(keys)) return keys\n  if ('current' in (keys as SecretBoxKeyring)) {\n    return (keys as SecretBoxKeyring).keys\n  }\n  return [keys as SecretBoxKey]\n}\n\n/** Version and key id, then the caller's context, as authenticated data. */\nfunction additionalData(keyId: string, context: string | undefined): Buffer {\n  return Buffer.from(`${SECRET_BOX_VERSION}\\u0000${keyId}\\u0000${context ?? ''}`, 'utf8')\n}\n\n/**\n * Seals a string under a key.\n *\n * `context` is bound into the tag, and the same value must be passed to\n * {@link openSecret}. `iv` is a test seam for a deterministic IV; never pass\n * one in production, because a repeated IV under one key breaks GCM entirely.\n */\nexport function sealSecret(\n  plaintext: string,\n  key: SecretBoxKey,\n  options: { context?: string; iv?: Uint8Array } = {},\n): string {\n  if (typeof plaintext !== 'string') {\n    throw new SecretBoxError('malformed', 'Only a string can be sealed.')\n  }\n  if (!key || key.material?.length !== SECRET_BOX_KEY_BYTES || !KEY_ID.test(key.id)) {\n    throw new SecretBoxError('invalid-key', 'The sealing key is not a usable secret box key.')\n  }\n  const iv = options.iv ? Buffer.from(options.iv) : randomBytes(IV_BYTES)\n  if (iv.length !== IV_BYTES) {\n    throw new SecretBoxError('malformed', `A secret box IV must be ${IV_BYTES} bytes.`)\n  }\n  const cipher = createCipheriv(ALGORITHM, Buffer.from(key.material), iv, {\n    authTagLength: TAG_BYTES,\n  })\n  cipher.setAAD(additionalData(key.id, options.context))\n  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])\n  const tag = cipher.getAuthTag()\n  return [\n    SECRET_BOX_VERSION,\n    key.id,\n    toBase64Url(iv),\n    toBase64Url(ciphertext),\n    toBase64Url(tag),\n  ].join('.')\n}\n\n/**\n * Opens a sealed value with whichever key in the ring it names.\n *\n * Throws {@link SecretBoxError}: `malformed` for anything not shaped like a\n * sealed value, `unsupported-version`, `unknown-key` when the ring has no key\n * by that id, and `refused` when authentication fails.\n */\nexport function openSecret(\n  sealed: string,\n  keys: SecretBoxKeyring | SecretBoxKey | readonly SecretBoxKey[],\n  options: { context?: string } = {},\n): OpenedSecret {\n  if (typeof sealed !== 'string' || !sealed) {\n    throw new SecretBoxError('malformed', 'The sealed value is empty.')\n  }\n  const parts = sealed.split('.')\n  if (parts.length !== 5) {\n    throw new SecretBoxError('malformed', 'The sealed value does not have five parts.')\n  }\n  const [version, keyId, ivPart, ciphertextPart, tagPart] = parts\n  if (version !== SECRET_BOX_VERSION) {\n    throw new SecretBoxError(\n      'unsupported-version',\n      'The sealed value was made by a scheme this reader does not open.',\n    )\n  }\n  if (!KEY_ID.test(keyId)) {\n    throw new SecretBoxError('malformed', 'The sealed value names an unusable key id.')\n  }\n  const iv = decodeBase64Url(ivPart, IV_BYTES)\n  // An empty ciphertext is a sealed empty string, and legitimate.\n  const ciphertext = ciphertextPart ? decodeBase64Url(ciphertextPart) : Buffer.alloc(0)\n  const tag = decodeBase64Url(tagPart, TAG_BYTES)\n\n  const key = asKeyring(keys).find((candidate) => candidate.id === keyId)\n  if (!key) {\n    throw new SecretBoxError(\n      'unknown-key',\n      'The sealed value was sealed under a key this reader does not hold.',\n    )\n  }\n  try {\n    const decipher = createDecipheriv(ALGORITHM, Buffer.from(key.material), iv, {\n      authTagLength: TAG_BYTES,\n    })\n    decipher.setAAD(additionalData(keyId, options.context))\n    decipher.setAuthTag(tag)\n    const plaintext = Buffer.concat([\n      decipher.update(ciphertext),\n      decipher.final(),\n    ]).toString('utf8')\n    return { plaintext, keyId }\n  } catch {\n    throw new SecretBoxError(\n      'refused',\n      'The sealed value did not authenticate: it was altered, or the key or context is wrong.',\n    )\n  }\n}\n\n/** Whether a value opened under an earlier key and should be sealed again. */\nexport function needsReseal(opened: OpenedSecret, keyring: SecretBoxKeyring): boolean {\n  return opened.keyId !== keyring.current.id\n}\n\n/** The id of the key a sealed value names, or `null` when it is not one. */\nexport function sealedSecretKeyId(sealed: unknown): string | null {\n  if (typeof sealed !== 'string') return null\n  const parts = sealed.split('.')\n  return parts.length === 5 && parts[0] === SECRET_BOX_VERSION && KEY_ID.test(parts[1])\n    ? parts[1]\n    : null\n}\n"],"names":["createCipheriv","createDecipheriv","createHmac","randomBytes","SECRET_BOX_VERSION","SECRET_BOX_KEY_BYTES","IV_BYTES","TAG_BYTES","ALGORITHM","KEY_ID","BASE64","BASE64URL","SecretBoxError","Error","code","message","name","toBase64Url","bytes","Buffer","from","toString","decodeBase64Url","part","expectedBytes","test","undefined","length","deriveSecretBoxKeyId","material","update","digest","subarray","createSecretBoxKey","id","trimmed","trim","replace","keyId","parseSecretBoxKeyring","value","entries","String","split","map","entry","filter","Boolean","keys","separator","indexOf","slice","ids","Set","key","has","add","current","asKeyring","Array","isArray","additionalData","context","sealSecret","plaintext","options","iv","cipher","authTagLength","setAAD","ciphertext","concat","final","tag","getAuthTag","join","openSecret","sealed","parts","version","ivPart","ciphertextPart","tagPart","alloc","find","candidate","decipher","setAuthTag","needsReseal","opened","keyring","sealedSecretKeyId"],"mappings":"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"}

package/src/lib/serialize/base64-isomorphic-decode.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Decode a base64 value to unicode string, safely in BOM and Node
+ * @param value - the base64 value to decode to unicode
+ * @param encoding - character encoding of return value 'utf8'|'utf16'|'unicode'
+ */
+export declare function base64IsomorphicDecode(value: string, encoding?: BufferEncoding): string;
+export default base64IsomorphicDecode;

package/src/lib/serialize/base64-isomorphic-decode.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Decode a base64 value to unicode string, safely in BOM and Node
+ * @param value - the base64 value to decode to unicode
+ * @param encoding - character encoding of return value 'utf8'|'utf16'|'unicode'
+ */ export function base64IsomorphicDecode(value, encoding = 'utf8') {
+    if (typeof window === 'undefined') {
+        return globalThis.Buffer.from(value, 'base64').toString(encoding);
+    }
+    return window.atob(value);
+}
+export default base64IsomorphicDecode;
+
+//# sourceMappingURL=base64-isomorphic-decode.js.map

package/src/lib/serialize/base64-isomorphic-decode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/util/tools/src/lib/serialize/base64-isomorphic-decode.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Decode a base64 value to unicode string, safely in BOM and Node\n * @param value - the base64 value to decode to unicode\n * @param encoding - character encoding of return value 'utf8'|'utf16'|'unicode'\n */\nexport function base64IsomorphicDecode(\n  value: string,\n  encoding: BufferEncoding = 'utf8',\n): string {\n  if (typeof window === 'undefined') {\n    return globalThis.Buffer.from(value, 'base64').toString(encoding)\n  }\n  return window.atob(value)\n}\nexport default base64IsomorphicDecode\n"],"names":["base64IsomorphicDecode","value","encoding","window","globalThis","Buffer","from","toString","atob"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;CAIC,GACD,OAAO,SAASA,uBACdC,KAAa,EACbC,WAA2B,MAAM;IAEjC,IAAI,OAAOC,WAAW,aAAa;QACjC,OAAOC,WAAWC,MAAM,CAACC,IAAI,CAACL,OAAO,UAAUM,QAAQ,CAACL;IAC1D;IACA,OAAOC,OAAOK,IAAI,CAACP;AACrB;AACA,eAAeD,uBAAsB"}

package/src/lib/serialize/base64-isomorphic-encode.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2023 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Encode a unicode value to base64 string, safely in BOM and Node
+ * @param value - the unicode value to encode to base64
+ * @param encoding - character encoding of value param 'utf8'|'utf16'|'unicode'
+ */
+export declare function base64IsomorphicEncode(value: string, encoding?: BufferEncoding): string;
+export default base64IsomorphicEncode;

package/src/lib/serialize/base64-isomorphic-encode.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2023 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Encode a unicode value to base64 string, safely in BOM and Node
+ * @param value - the unicode value to encode to base64
+ * @param encoding - character encoding of value param 'utf8'|'utf16'|'unicode'
+ */ export function base64IsomorphicEncode(value, encoding = 'utf8') {
+    if (typeof window === 'undefined') {
+        return globalThis.Buffer.from(value, encoding).toString('base64');
+    }
+    return window.btoa(value);
+}
+export default base64IsomorphicEncode;
+
+//# sourceMappingURL=base64-isomorphic-encode.js.map

package/src/lib/serialize/base64-isomorphic-encode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/util/tools/src/lib/serialize/base64-isomorphic-encode.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2023 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Encode a unicode value to base64 string, safely in BOM and Node\n * @param value - the unicode value to encode to base64\n * @param encoding - character encoding of value param 'utf8'|'utf16'|'unicode'\n */\nexport function base64IsomorphicEncode(\n  value: string,\n  encoding: BufferEncoding = 'utf8',\n): string {\n  if (typeof window === 'undefined') {\n    return globalThis.Buffer.from(value, encoding).toString('base64')\n  }\n  return window.btoa(value)\n}\nexport default base64IsomorphicEncode\n"],"names":["base64IsomorphicEncode","value","encoding","window","globalThis","Buffer","from","toString","btoa"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;CAIC,GACD,OAAO,SAASA,uBACdC,KAAa,EACbC,WAA2B,MAAM;IAEjC,IAAI,OAAOC,WAAW,aAAa;QACjC,OAAOC,WAAWC,MAAM,CAACC,IAAI,CAACL,OAAOC,UAAUK,QAAQ,CAAC;IAC1D;IACA,OAAOJ,OAAOK,IAAI,CAACP;AACrB;AACA,eAAeD,uBAAsB"}

package/src/lib/serialize/json-deserialize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Generates a value into a **_JSON_** parsing representation of a value
+ *
+ * @see {@link jsonSerialize}
+ * @see {@link JSON.parse}
+ * @see {@link JSON.stringify}
+ */
+export declare function jsonDeserialize(...args: Parameters<typeof JSON.parse>): ReturnType<typeof JSON.parse>;
+export default jsonDeserialize;

package/src/lib/serialize/json-deserialize.js

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Generates a value into a **_JSON_** parsing representation of a value
+ *
+ * @see {@link jsonSerialize}
+ * @see {@link JSON.parse}
+ * @see {@link JSON.stringify}
+ */ export function jsonDeserialize(...args) {
+    return JSON.parse(...args);
+}
+export default jsonDeserialize;
+
+//# sourceMappingURL=json-deserialize.js.map

package/src/lib/serialize/json-deserialize.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/util/tools/src/lib/serialize/json-deserialize.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Generates a value into a **_JSON_** parsing representation of a value\n *\n * @see {@link jsonSerialize}\n * @see {@link JSON.parse}\n * @see {@link JSON.stringify}\n */\nexport function jsonDeserialize(...args: Parameters<typeof JSON.parse>): ReturnType<typeof JSON.parse> {\n  return JSON.parse(...args)\n}\nexport default jsonDeserialize\n"],"names":["jsonDeserialize","args","JSON","parse"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;CAMC,GACD,OAAO,SAASA,gBAAgB,GAAGC,IAAmC;IACpE,OAAOC,KAAKC,KAAK,IAAIF;AACvB;AACA,eAAeD,gBAAe"}