@ibgib/core-gib 0.0.4

package/src/common/encrypt/encrypt-types.mts

@@ -0,0 +1,130 @@
+import { IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/index.mjs';
+import { IbGibAddr, } from '@ibgib/ts-gib';
+import { HashAlgorithm } from '@ibgib/helper-gib';
+import { SaltStrategy } from '@ibgib/encrypt-gib';
+import { ENCRYPTION_REL8N_NAME } from './encrypt-constants.mjs';
+
+
+export type SecretType = "password";
+export const SecretType = {
+    password: 'password' as SecretType,
+}
+export const VALID_SECRET_TYPES = Object.values(SecretType).concat();
+
+export interface SecretInfo {
+    name: string;
+    description?: string;
+    expirationUTC: string;
+    type: SecretType;
+}
+
+export interface SecretInfo_Password extends SecretInfo {
+    type: 'password';
+    /**
+     * We won't save the entire hash, just the hash.slice(16),
+     * because we are not checking to give authority, we are
+     * just checking to see if the user entered the same
+     * password for their own check.
+     *
+     * ## warnings
+     * NOTHING giving actual authorization should look at this.
+     */
+    hash16816_SHA256: string;
+    /**
+     * Public hint to help you remember your secret (or help the bad person
+     * attack your secret).
+     */
+    hint?: string;
+}
+export type SecretData_V1 = SecretInfo; // extend this with logical OR later
+
+export interface SecretRel8ns_V1 extends IbGibRel8ns_V1 {
+}
+
+export interface SecretIbGib_V1 extends IbGib_V1<SecretData_V1, SecretRel8ns_V1> {
+}
+
+export interface EncryptionInfo {
+    name: string;
+    description?: string;
+    method: EncryptionMethod;
+}
+
+export type EncryptionMethod = 'encrypt-gib (weak)';
+export const EncryptionMethod = {
+    encrypt_gib_weak: 'encrypt-gib (weak)' as EncryptionMethod,
+}
+
+export interface EncryptionInfo {
+    method: EncryptionMethod,
+}
+
+export interface EncryptionInfo_EncryptGib extends EncryptionInfo {
+    method: 'encrypt-gib (weak)'
+    /**
+     * This is the algorithm that encrypt-gib will use in its
+     * internal hashing round function to encrypt the data.
+     */
+    hashAlgorithm: HashAlgorithm;
+    /**
+     * This is an initial number of recursions to perform to "get farther away"
+     * from the password. It is a one-time cost at the beginning of the
+     * entire encryption process, so it does not cost more with more data.
+     */
+    initialRecursions: number;
+    /**
+     * This is the number of internal hashes per round function, which is per
+     * hex character of data. So the more recursions here, the longer it is
+     * going to take to encrypt/decrypt.
+     */
+    recursionsPerHash?: number;
+    /**
+     * Salt used throughout hashing in encryption/decryption. The longer and
+     * more random, the better for security. But there is also a resource cost.
+     */
+    salt: string;
+    /**
+     * Stronger are the perHash options.
+     *
+     *    'prependPerHash' | 'appendPerHash' | 'initialPrepend' | 'initialAppend';
+     */
+    saltStrategy?: SaltStrategy;
+    /**
+     * The encrypted data is a delimited list of indices.
+     *
+     * @default "," (comma-delimited)
+     */
+    encryptedDataDelimiter?: string;
+}
+
+export type EncryptionData_V1 = EncryptionInfo_EncryptGib; // extend this with logical OR later
+
+export interface EncryptionRel8ns_V1 extends IbGibRel8ns_V1 { }
+
+/**
+ * IbGib that represents encryption settings
+ */
+export interface EncryptionIbGib extends IbGib_V1<EncryptionData_V1, EncryptionRel8ns_V1> { }
+
+/**
+ * Data for the actual encrypted ciphertext.
+ */
+export interface CiphertextData<TMetadata = any> {
+    ciphertext?: string;
+    metadata?: TMetadata;
+}
+
+/**
+ * Rel8ns for the actual encrypted ciphertext
+ */
+export interface CiphertextRel8ns extends IbGibRel8ns_V1 {
+    [ENCRYPTION_REL8N_NAME]?: IbGibAddr[];
+}
+
+/**
+ * Ibgib for the actual encrypted content, as opposed to the
+ * encryption secret (password) or encryption method/algorithm.
+ */
+export interface CiphertextIbGib_V1<TMetadata = any>
+    extends IbGib_V1<CiphertextData<TMetadata>, CiphertextRel8ns> {
+}

package/src/common/error/error-constants.mts

@@ -0,0 +1,8 @@
+/**
+ * Used in ErrorIbGib_V1.ib
+ */
+export const DEFAULT_ERROR_MSG_IB_SUBSTRING_LENGTH = 20;
+/**
+ * regexp for an error ibgib's (ErrorIbGib_V1) ib property.
+ */
+export const ERROR_IB_REGEXP = /^error (\w+) ([a-fA-F\d]{32}|undefined)$/;

package/src/common/error/error-helper.mts

@@ -0,0 +1,155 @@
+import { Ib } from '@ibgib/ts-gib';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/index.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
+import { ErrorData_V1, ErrorIbGib_V1, ErrorRel8ns_V1 } from './error-types.mjs';
+import { constantIbGib } from '../other/ibgib-helper.mjs';
+import { DEFAULT_ERROR_MSG_IB_SUBSTRING_LENGTH, ERROR_IB_REGEXP } from './error-constants.mjs';
+import { ERROR_MSG_LOCATION_ONLY_REGEXP, ERROR_MSG_WITH_ID_CAPTURE_GROUPS_REGEXP } from '@ibgib/helper-gib';
+
+
+const logalot = GLOBAL_LOG_A_LOT || false;
+
+/**
+ * Generates an ib based on a raw error msg.
+ *
+ * ## future
+ *
+ * If this is changed in the future, then without versioning of some sort, this
+ * will change the error constant ibgibs that rely on this functions
+ * deterministic qualities.
+ *
+ * @returns the error's `ib`
+ */
+export function getErrorIb({
+    rawMsg,
+}: {
+    rawMsg: string,
+}): Ib {
+    const lc = `[${getErrorIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting...`); }
+        const parsed = parseRawErrorMsg({ rawMsg });
+        const saferText = parsed.body.replace(/\s/g, '_').replace(/\W/g, '');
+        let msgSlice: string;
+        if (saferText.length > DEFAULT_ERROR_MSG_IB_SUBSTRING_LENGTH) {
+            msgSlice =
+                saferText.substring(0, DEFAULT_ERROR_MSG_IB_SUBSTRING_LENGTH);
+        } else if (saferText.length > 0) {
+            msgSlice = saferText;
+        } else {
+            // msg only has characters/nonalphanumerics ?
+            throw new Error(`(UNEXPECTED) error msg should have characters/alphanumerics... (E: a3b9cd11a44cc7892a748819c2885422)`);
+        }
+
+        return `error ${msgSlice} ${parsed.uuid ?? 'undefined'}`;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Parses a raw error/exception message.
+ *
+ * If it has sections that I personally use (usually), then it will break that
+ * out. otherwise, it will just have the `rawMsg` as the msg body and raw msg.
+ *
+ * @see {@link ErrorData_V1}
+ */
+export function parseRawErrorMsg({
+    rawMsg,
+}: {
+    rawMsg: string,
+}): ErrorData_V1 {
+    const lc = `[${parseRawErrorMsg.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting...`); }
+        if (!rawMsg) { throw new Error(`(UNEXPECTED) rawMsg required (E: e5bd3b433a1781ebe885534cd2495622)`); }
+
+        let data: ErrorData_V1;
+        let regexResult = rawMsg.match(ERROR_MSG_WITH_ID_CAPTURE_GROUPS_REGEXP);
+        if (regexResult) {
+            // has id section
+            const [_, location, unexpectedAtStart, body, idSection, unexpectedAtEnd] = regexResult;
+            if (!body) { throw new Error(`invalid error msg body (E: a675e6855cca96519d33d44ea5400922)`); }
+            data = {
+                success: false,
+                raw: rawMsg,
+                body: body?.trim(),
+                uuid: idSection.slice(4, 36),
+            };
+            if (location) { data.location = location; }
+            if (unexpectedAtStart || unexpectedAtEnd) { data.unexpected = true; }
+        } else {
+            // no id or unexpected regex (maybe changed?)
+            data = {
+                success: false,
+                raw: rawMsg,
+                body: rawMsg,
+            };
+            let regexResultLocation = rawMsg.match(ERROR_MSG_LOCATION_ONLY_REGEXP);
+            if (regexResultLocation) {
+                const [_, location] = regexResultLocation;
+                data.location = location;
+            }
+            if (rawMsg.toLowerCase().includes(`(unexpected)`)) {
+                data.unexpected = true;
+            }
+        }
+
+        return data;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Builds a "constant" error ibgib based on the given `rawMsg`.
+ *
+ * @returns constant error ibgib built from given `rawMsg`
+ *
+ * @see {@link ErrorData_V1}
+ * @see {@link ErrorIbGib_V1}
+ */
+export function errorIbGib({ rawMsg }: { rawMsg: string }): Promise<ErrorIbGib_V1> {
+    const lc = `[${errorIbGib.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting...`); }
+
+        return constantIbGib<ErrorData_V1, ErrorRel8ns_V1>({
+            parentPrimitiveIb: 'error',
+            ib: getErrorIb({ rawMsg }),
+            data: parseRawErrorMsg({ rawMsg }),
+            ibRegExpPattern: ERROR_IB_REGEXP.source,
+        });
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+export function isError({
+    ibGib
+}: {
+    ibGib: IbGib_V1
+}): boolean {
+    const lc = `[${isError.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting...`); }
+        if (!ibGib) { throw new Error(`ibGib required (E: 1d756fbbd96f1734b97ba013537ed522)`); }
+        return ibGib.ib.startsWith('error ');
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/common/error/error-types.mts

@@ -0,0 +1,62 @@
+import { IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/index.mjs';
+
+/**
+ * I format my errors nowadays usually using an id and a possible (unexpected) flag.
+ * Sometimes I put the unexpected flag at the beginning, sometimes at the end.
+ */
+export interface ErrorData_V1 {
+    /**
+     * raw error message
+     */
+    raw: string;
+    /**
+     * I usually have lc's (log contexts) all over my code, if that isn't obvious or
+     * if you're not looking at the code. Anyway, I prepend error/info/warning msgs
+     * with the location like this:
+     *
+     * ```
+     * [MyClass][Foo] some error (E: hash123)
+     * ```
+     *
+     * So the bits in the brackets are the location. In this case, it's
+     * `[MyClass][Foo]` meaning in the function `Foo` on the class `MyClass`.
+     */
+    location?: string;
+    /**
+     * error message sans any metadata
+     */
+    body: string;
+    /**
+     * if the error is thrown more of an assertion, and it's an edge case just
+     * weird error, then I often add `"(UNEXPECTED)"` to the msg. This flag
+     * indicates that.
+     */
+    unexpected?: boolean;
+    /**
+     * I often include error ids.
+     */
+    uuid?: string;
+    /**
+     * All errors should have `errorIbGib.data.success` = false
+     */
+    success: false;
+}
+
+export interface ErrorRel8ns_V1 extends IbGibRel8ns_V1 {
+
+}
+
+/**
+ * Encapsulates data on errors that are thrown in this code base.
+ *
+ * ## driving intent
+ *
+ * I'm creating this for error constant ibgibs when I want to wrap an error
+ * message in an ibgib for whatever reason.
+ *
+ * Specifically I'm working on the random robbot and want the ability to return an error
+ * or add an error to a context ibgib.
+ */
+export interface ErrorIbGib_V1 extends IbGib_V1<ErrorData_V1, ErrorRel8ns_V1> {
+
+}

package/src/common/form/form-helper.mts

@@ -0,0 +1,253 @@
+
+import { getRegExp, UUID_REGEXP } from '@ibgib/helper-gib';
+// import { DynamicForm, FormItemInfo } from '../../ibgib-forms/types/form-items';
+import { GLOBAL_LOG_A_LOT, SAFE_SPECIAL_CHARS } from '../../core-constants.mjs';
+import { DynamicForm, FormItemInfo } from './form-items.mjs';
+// import { getRegExp } from './utils';
+
+const logalot = GLOBAL_LOG_A_LOT || false;
+
+/**
+ * Fluent-style builder helper class.
+ *
+ * I'm making this to share common fields' settings among witness classes.
+ *
+ * Descend from this class for sharing other commonalities.
+ */
+export class DynamicFormBuilder {
+    protected lc: string = `[${DynamicFormBuilder.name}]`;
+    protected items: FormItemInfo[] = [];
+    protected what: string = '';
+    /**
+     * pool of uuids pre-calculated to be passed in to the builder. if this is
+     * falsy, then it will use a Math.random() based approach.
+     */
+    protected idPool: string[] = [];
+
+    /**
+     * hacky wrapper for this.idPool.pop()
+     */
+    protected getNewId(): string {
+        const lc = `${this.lc}[${this.getNewId.name}]`;
+        if (this.idPool?.length > 0) {
+            return this.idPool.pop() ?? '';
+        } else {
+            // weak implementation...
+            let resultArray: string[] = [];
+            const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+            const charLength = chars.length;
+            for (let i = 0; i < 32; i++) {
+                let charIndex = Math.floor(Math.random() * charLength);
+                resultArray.push(chars[charIndex]);
+            }
+            let id = resultArray.join('');
+            if (logalot) { console.log(`${lc} id: ${id} (I: c6591ffee6d5bbea79ed19cfa6630422)`); }
+            return id;
+        }
+    }
+
+    /**
+     * Start fluent calls with this.
+     */
+    forA({
+        what,
+    }: {
+        /**
+         * Common name for the reified concrete type of the witness.
+         *
+         * Used in things like placeholders, descriptions, etc.
+         *
+         * @example "robbot" or "space"
+         */
+        what: string,
+    }): DynamicFormBuilder {
+        this.what = what || 'thingy';
+        return this;
+    }
+
+    protected addItem(item: FormItemInfo) {
+        if (!item.uuid) { item.uuid = this.getNewId(); }
+        this.items.push(item);
+    }
+
+    /**
+     * Empty function simply for more natural looking fluent syntax.
+     *
+     * You can override this for custom form builders that descend from this
+     * class.
+     *
+     * @returns this
+     */
+    with<T extends DynamicFormBuilder>({
+        idPool,
+    }: {
+        /**
+         * pre-built pool of uuids to draw from. this builder
+         * will mutate this array.
+         */
+        idPool?: string[],
+    }): T {
+        if (idPool) { this.idPool = idPool; }
+        return this as any as T;
+    }
+
+    /**
+     * I'm not a great fluent builder writer for TypeScript,
+     * and this function acts as a caster for which members of
+     * which concrete classes to expose for the proceeding builder lines.
+     *
+     *
+     * Basically, you use this to typecast the builder, possibly redundantly since
+     * I don't have any ordering implemented atow.
+     *
+     * @returns typecasted fluent builder
+     */
+    and<T extends DynamicFormBuilder>(): T { return this as any as T; }
+
+    name<T extends DynamicFormBuilder>({
+        of: value,
+        required = true,
+    }: {
+        of: string,
+        required?: boolean,
+    }): T {
+        this.addItem({
+            // witness.data.name
+            name: "name",
+            description: `What to call this ${this.what}. Doesn't have to be unique, no spaces, up to 32 alphanumerics/underscores in length.`,
+            label: "Name",
+            placeholder: `e.g. "bob_the_cool"`,
+            regexp: getRegExp({ min: 1, max: 32, noSpaces: true }),
+            regexpErrorMsg: '1 to 32 characters, no spaces, underscores allowed.',
+            required,
+            dataType: 'text',
+            value,
+        });
+        return this as any as T;
+    }
+
+    description({
+        of: value,
+        required,
+        defaultValue,
+    }: {
+        of: string,
+        required?: boolean,
+        defaultValue?: string,
+    }): DynamicFormBuilder {
+        this.addItem({
+            // witness.data.description
+            name: "description",
+            description: `Description/notes for this ${this.what}.`,
+            label: "Description",
+            placeholder: `Describe these ${this.what} settings here...`,
+            regexp: getRegExp({ min: 0, max: 155, chars: SAFE_SPECIAL_CHARS }),
+            regexpErrorMsg: `0 to 155 alphanumerics or any of ${SAFE_SPECIAL_CHARS}`,
+            // regexpSource: getRegExp({min: 0, max: 155, chars: SAFE_SPECIAL_CHARS}).source,
+            dataType: 'textarea',
+            required,
+            defaultValue,
+            value,
+        });
+        return this;
+    }
+
+    classname({
+        of,
+        required = true,
+    }: {
+        of: string,
+        required?: boolean,
+    }): DynamicFormBuilder {
+        this.addItem({
+            // witness.data.classname
+            name: "classname",
+            description: `Technical setting that is the name of the ${this.what}'s class in computer code.`,
+            label: "Classname",
+            regexp: getRegExp({ min: 1, max: 128, noSpaces: true }),
+            regexpErrorMsg: `1 to 128 alphanumerics or underscores without spaces`,
+            // regexpSource: getRegExp({min: 1, max: 128, noSpaces: true}).source,
+            dataType: 'text',
+            value: of,
+            readonly: true,
+            required,
+        });
+        return this;
+    }
+
+    uuid({
+        of,
+        label,
+        required,
+    }: {
+        of: string,
+        label?: string,
+        required?: boolean,
+    }): DynamicFormBuilder {
+        this.addItem({
+            // witness.data.uuid
+            name: "uuid",
+            description: `Unique(ish) id of the ${this.what}.`,
+            label: label ?? "ID",
+            dataType: 'text',
+            value: of,
+            regexp: UUID_REGEXP,
+            regexpErrorMsg: '1 to 256 alphanumerics, underscores, dots, hyphens allowed.',
+            readonly: true,
+            required,
+        });
+        return this;
+    }
+
+    version({
+        of,
+        required,
+    }: {
+        of: string | undefined,
+        required?: boolean,
+    }): DynamicFormBuilder {
+        this.addItem({
+            // witness.data.version
+            name: "version",
+            description: `Technical setting indicating the version of the ${this.what}.`,
+            label: "Version",
+            dataType: 'text',
+            value: of || '',
+            readonly: true,
+            required,
+        });
+        return this;
+    }
+
+    /**
+     * To pass in a completely customized item info.
+     *
+     * @returns `this` for fluent builder
+     */
+    customItem(item: FormItemInfo): DynamicFormBuilder {
+        this.addItem(item);
+        return this;
+    }
+
+
+    outputItems(): FormItemInfo[] {
+        return this.items;
+    }
+
+    outputForm({
+        formName,
+        label,
+    }: {
+        formName: string,
+        label?: string,
+    }): DynamicForm {
+        return {
+            name: formName,
+            // description: this.description ?? `This is a form for a ${this.what}`,
+            description: `This is a form for a ${this.what}`,
+            label: label ?? this.what,
+            items: this.items,
+        } as DynamicForm;
+    }
+}
+