@ibgib/core-gib 0.0.48 → 0.0.50

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

@@ -0,0 +1,215 @@
+/**
+ * @module secret types (and enums)
+ */
+
+import { HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.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';
+
+    /**
+     * @see {@link CheckIfPasswordProbablyCorrectInfo}
+     */
+    passwordProbablyCorrectInfo: CheckIfPasswordProbablyCorrectInfo;
+
+    /**
+     * Public hint to help you remember your secret (or help the bad person
+     * attack your secret).
+     */
+    hint?: string;
+}
+
+/**
+ * This contains information for doing a **convenience check** of whether or
+ * not the user/consumer has entered a password that is "probably" correct.
+ *
+ * ## READ THIS
+ *
+ * Distributed sovereignty has different requirements than a trusted server
+ * approach when it comes to handling secrets.
+ *
+ * ### trusted servers store entire hashes for authentication
+ *
+ * In a trusted server approach, we will check the password against some hashing
+ * mechanism with varying implementation details. But we will almost certainly
+ * check against the entire hash, because we will decide authentication based on
+ * this proof.
+ *
+ * ### distributed data works differently
+ *
+ * In the distributed model, however, the only utility of a password is in
+ * encryption and signatures. So when a user/consumer enters a password, it
+ * actually **does** something, i.e., creates derivative data. Either it creates
+ * an encrypted file or performs a signature (I hesitate to discuss asymmetric
+ * encryption because I still don't believe in it, and when keystones are
+ * implemented in ibgib, passwords will evolve the stone (it works _somewhat_
+ * similarly to a double-ratchet algorithm but is more hardened and expressive
+ * because it works on top of ibgib's already-established "chaining"
+ * infrastructure)).
+ *
+ * But the question is:
+ *   **How does the user/consumer know that they entered the right password?**
+ *
+ * ### we can't store entire hashes
+ *
+ * In the distributed model, we assume a brute-forcer will have access to the
+ * encrypted data and any metadata we might store. This includes those would-be
+ * hashes and that would be bad - even if they are randomly salted.
+ *
+ * This is because this approach would preclude the ability for the user to
+ * encrypt some large data with mitigations against short-circuit decryption
+ * until the entire data block was decrypted (I refer you to encrypt-gib
+ * documentation here). IOW, the brute-forcer would only have to use the
+ * password and check against the hash, which can be an extremely quick
+ * operation - even if we set iterations insanely high on some KDF, this still
+ * would provide a relatively quick avenue for brute force attacks.
+ *
+ * ### we can store partial hashes
+ *
+ * We won't save the entire hash, just some substring of the hash. (We could
+ * conceivably store other metadata that checks against the hash, e.g., parity
+ * checks like the number of 1s, 2s, etc.).
+ *
+ * ### partial hash dynamics
+ *
+ * * The larger the partial hash, the less likely false collisions are produced.
+ *   * when a user typos a password, we do NOT want a false collision.
+ *   * when a brute-forcer makes a password attempt, we DO want a false
+ *     collision.
+ * * a user's **unique** typos compose the set that we want to avoid false
+ *   collisions.
+ *   * the same typo only counts once.
+ *
+ * So we want to...
+ * * maximize the time wasted in brute forcing
+ *   * or IOW, minimize the information gained by the brute forcer
+ *   * this will statistically slow down brute force attacks that work against
+ *     this information alone.
+ * * minimize the inconvenience by a password failure due to a false collision
+ *   by the legitimate user/consumer.
+ *   * there should be in place a well-hardened fail path for when the false
+ *     password is given but the false collision allows it to pass the initial
+ *     quick check phase.
+ *
+ * ### my implementation notes
+ *
+ * I am not doing this mathematically/rigorously, because that would take way
+ * too long, rather I am working from...
+ * * my personal experience with searching for hashes in the ibgib code bases.
+ *   * Most ibgib codebase error messages are accompanied by a hash to uniquely
+ *     identify the error.
+ *   * I often search the codebase based on a substring of this when I am
+ *     troubleshooting.
+ *   * atow (02/2024) there are 1171 of these hashes in just core-gib.
+ *   * To get a unique hash, the absolute MOST I have to actually enter is 4 or
+ *     5 letters
+ *     * 5 is extremely rare.
+ * * unit testing observations
+ *   * I've found that 4 letters gives false collisions on average every 900-ish
+ *     hashes.
+ *
+ * As such, I am setting the length to 4. But note that in consuming code, we
+ * always just check for the substring, so changing this value in the future
+ * should not affect code a la an exception thrown, but rather, it will just
+ * change this dynamic of good faith typos vs. brute force cracking.
+ *
+ * ## warnings
+ *
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ */
+export interface CheckIfPasswordProbablyCorrectInfo {
+    /**
+     * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+     * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+     * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+     * @see {CheckIfPasswordProbablyCorrectInfo}
+     *
+     * substring contained in the resultant recursive hash built on the password
+     * and other parameters of this info.
+     *
+     * other parameters:
+     * * {@link recursions}
+     * * {@link saltPrependedPerHash}
+     * * {@link algorithm}
+     */
+    substring: string;
+    /**
+     * the number of times to recursively call the hash function, analogous to a
+     * naive key stretching algorithm.
+     */
+    recursionCount: number;
+    /**
+     * salt that will be prepended to the password/intermediate hash each hash
+     * round.
+     */
+    saltPrependedPerHash: string;
+    /**
+     * hash algorithm to use per hash round.
+     */
+    algorithm: HashAlgorithm;
+}
+
+// export type SecretData_V1 extends = SecretInfo; // extend this with logical OR later
+/**
+ * ibgib's intrinsic data.
+ *
+ * atow (02/2024) we are doing most of this in {@link SecretInfo} (from ionic-gib port)
+ *
+ * @see {@link SecretInfo}
+ * @see {@link IbGib_V1.data}
+ * @see {@link SecretIbGib_V1}
+ */
+export interface SecretData_V1 extends IbGibData_V1, SecretInfo {
+}
+
+/**
+ * rel8ns (named edges/links in DAG) go here.
+ *
+ * @see {@link IbGib_V1.rel8ns}
+ * @see {@link SecretIbGib_V1}
+ */
+export interface SecretRel8ns_V1 extends IbGibRel8ns_V1 {
+    // /**
+    //  * required rel8n. for most, put in secret-constants.mts file
+    //  *
+    //  * @see {@link REQUIRED_REL8N_NAME}
+    //  */
+    // [REQUIRED_REL8N_NAME]: IbGibAddr[];
+    // /**
+    //  * optional rel8n. for most, put in secret-constants.mts file
+    //  *
+    //  * @see {@link OPTIONAL_REL8N_NAME}
+    //  */
+    // [OPTIONAL_REL8N_NAME]?: IbGibAddr[];
+}
+
+/**
+ * this is the ibgib object itself.
+ *
+ * If this is a plain ibgib data only object, this acts as a dto. You may also
+ * want to generate a witness ibgib, which is slightly different, for ibgibs
+ * that will have behavior (i.e. methods).
+ *
+ * @see {@link SecretData_V1}
+ * @see {@link SecretRel8ns_V1}
+ */
+export interface SecretIbGib_V1 extends IbGib_V1<SecretData_V1, SecretRel8ns_V1> {
+
+}

package/src/common/secret/secret.respec.mts

@@ -0,0 +1,175 @@
+/**
+ * @module secret respec
+ *
+ * we gotta test our secret
+ */
+
+// import { cwd, chdir, } from 'node:process';
+// import { statSync } from 'node:fs';
+// import { mkdir, } from 'node:fs/promises';
+// import { ChildProcess, exec, ExecException } from 'node:child_process';
+import * as pathUtils from 'path';
+
+import {
+    firstOfAll, firstOfEach, ifWe, ifWeMight, iReckon,
+    lastOfAll, lastOfEach, respecfully, respecfullyDear
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+
+import {
+    extractErrorMsg, delay, getSaferSubstring,
+    getTimestampInTicks, getUUID, pretty, HashAlgorithm, clone,
+} from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
+import { getCheckIfPasswordProbablyCorrectInfo, passwordProbablyCorrect } from './secret-helper.mjs';
+import { hash16816 } from '../other/ibgib-helper.mjs';
+import { DEFAULT_PASSWORD_CHECK_SUBSTRING_LENGTH } from './secret-constants.mjs';
+
+/**
+ * for verbose logging
+ */
+const logalot = GLOBAL_LOG_A_LOT; // change this when you want to turn off verbose logging
+
+const lcFile: string = `[${pathUtils.basename(import.meta.url)}]`;
+
+const correctPasswords = [
+    'yo',
+    'hey this is a password',
+    'jwoiejf oiwejf oiewjf owiefhw9e8hf982y98y2398f 2398f oijsd oifj woeihfew9hg 9we8u98 u34793824798au s9d8u 9a8syg 98ywheg y98uy9*(*^*&#^ $(*&#@( *$& @(#*$&(* #@^T%(YIUdyf 98wye fuwehfiu hweiufh iugh iuh j'
+];
+const substringLength = DEFAULT_PASSWORD_CHECK_SUBSTRING_LENGTH;
+
+const recursionCount = 168;
+const algorithm: HashAlgorithm = 'SHA-256';
+const saltPrependedPerHash = '';
+
+const blockName = `CheckIfPasswordProbablyCorrect`;
+await respecfully(maam, blockName, async () => {
+    const lc = `${lcFile}[${blockName}]`;
+
+    if (logalot) { console.time(lc) }
+
+    await respecfully(maam, `checking passwords`, async () => {
+        await ifWe(maam, `ensure correct password always succeeds`, async () => {
+            // these are to mimic legitimate setting of hash16816 substring and
+            // subsequent legit correct password entries.  they should always
+            // succeed, i.e., the hash should always contain the substring.
+            const iterationsToCheck = 10;
+
+            let failed = false;
+            for (let i = 0; i < correctPasswords.length; i++) {
+                const password = correctPasswords[i];
+                const fullHash = await hash16816({
+                    s: password,
+                    algorithm,
+                    recursionCount,
+                    saltPrependedPerHash,
+                });
+                for (let num = 0; num < iterationsToCheck; num++) {
+                    const public_checkInfo = await getCheckIfPasswordProbablyCorrectInfo({
+                        password,
+                        substringLength,
+                        algorithm,
+                        saltPrependedPerHash,
+                        recursionCount
+                    });
+                    const { substring } = public_checkInfo;
+                    // manually check (requires us to know internals of
+                    // passwordProbablyCorrect fn)
+                    if (!fullHash.includes(substring)) {
+                        failed = true;
+                        break;
+                    }
+                    // check directly via the fn consumer will use
+                    const resProbablyCorrect = await passwordProbablyCorrect({
+                        password,
+                        checkInfo: clone(public_checkInfo),
+                    });
+                    if (!resProbablyCorrect) {
+                        failed = true;
+                        break;
+                    }
+                }
+            }
+            iReckon(sir, failed).asTo('failed').isGonnaBeFalse();
+        });
+    });
+
+    if (logalot) { console.timeLog(lc) }
+
+    await respecfully(maam, `bruteforcing check`, async () => {
+        await ifWe(maam, `try to brute force, we get a collision`, async () => {
+            /**
+             * I've done larger numbers than these, but would be a waste of time to
+             * do more now. change this as needed for custom testing.
+             */
+            const numBruteForceTests = 3;
+            /**
+             * i just want to average the iterations required to tweak what i should
+             * be using as a substringLength.
+             */
+            let totalAttemptsForFalseCollisions = 0;
+            for (let i = 0; i < numBruteForceTests; i++) {
+                const correctPassword = correctPasswords[i % correctPasswords.length];
+                const correctFullHash = await hash16816({
+                    s: correctPassword,
+                    algorithm,
+                    recursionCount,
+                    saltPrependedPerHash,
+                });
+                /**
+                 * when initially creating the secret, the user will store this
+                 * known substring in the `secretInfo.passwordProbablyCorrectSubstring`.
+                 * from the attacker's POV this substring is public knowledge, and
+                 * the attacker is going to try to brute force against this
+                 * substring. we want there to be at least one collistion that has
+                 * this substring.
+                 *
+                 * "public" as in the would-be brute forcer knows this (and other
+                 * check info) as public metadata
+                 */
+                const public_checkInfo = await getCheckIfPasswordProbablyCorrectInfo({
+                    password: correctPassword,
+                    substringLength,
+                    algorithm,
+                    recursionCount,
+                    saltPrependedPerHash,
+                });
+                const { substring: publicSubstring } = public_checkInfo;
+                /**
+                 * some arbitrarily "large" number (really this will be much higher
+                 * but we are testing in a respec here).
+                 */
+                const bruteForceAttempts = 1_000_000;
+                let foundFalseCollision = false;
+                for (let j = 0; j < bruteForceAttempts; j++) {
+                    const passwordAttempt = j.toString();
+                    const fullHashAttempt = await hash16816({
+                        s: passwordAttempt,
+                        algorithm,
+                        recursionCount,
+                        saltPrependedPerHash,
+                    });
+                    if (fullHashAttempt.includes(publicSubstring)) {
+                        // their invalid password attempt found a false collision
+                        foundFalseCollision = true;
+                        totalAttemptsForFalseCollisions += j;
+                        console.log(`j: ${j}`);
+                        console.log(`publicSubstring: ${publicSubstring}`);
+                        console.log(`fullHashAttempt: ${fullHashAttempt}`);
+                        console.log(`correctFullHash: ${correctFullHash}`);
+                        break;
+                    }
+                }
+                iReckon(maam, foundFalseCollision).asTo('foundFalseCollision').isGonnaBeTrue();
+                // not really for testing, but i want to see the average attempts required
+                let averageAttemptsPerFalseCollision = Math.floor(totalAttemptsForFalseCollisions / (i + 1));
+                console.log(`averageAttemptsPerFalseCollision: ${averageAttemptsPerFalseCollision}`);
+            }
+        });
+    });
+
+    if (logalot) { console.timeEnd(lc) }
+
+});

package/src/witness/space/metaspace/metaspace-base.mts

@@ -25,7 +25,6 @@ import { RootData } from '../../../common/root/root-types.mjs';
 import {
     CiphertextData, CiphertextIbGib_V1, CiphertextRel8ns,
     EncryptionData_V1, EncryptionIbGib, EncryptionInfo_EncryptGib,
-    SecretData_V1, SecretIbGib_V1, SecretInfo_Password
 } from '../../../common/encrypt/encrypt-types.mjs';
 import { RobbotIbGib_V1 } from '../../../witness/robbot/robbot-types.mjs';
 import { AppIbGib_V1 } from '../../../witness/app/app-types.mjs';
@@ -55,7 +54,7 @@ import { IbGibCacheService } from '../../../common/cache/cache-types.mjs';
 import { BOOTSTRAP_DATA_KNOWN_SPACE_IDS_KEY, BOOTSTRAP_IBGIB_ADDR } from '../../../witness/space/bootstrap/bootstrap-constants.mjs';
 import { DEFAULT_LOCAL_SPACE_DESCRIPTION, DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS, DEFAULT_MAX_RETRIES_GET_DEPENDENCY_GRAPH_OUTERSPACE, DEFAULT_MS_BETWEEN_RETRIES_GET_DEPENDENCY_GRAPH_OUTERSPACE, DEFAULT_SECONDS_VALID_LOCAL, PERSIST_OPTS_AND_RESULTS_IBGIBS_DEFAULT, SYNC_SPACE_REL8N_NAME } from '../../../witness/space/space-constants.mjs';
 import { IBGIB_BASE_DIR, IBGIB_BASE_SUBPATH, IBGIB_BIN_SUBPATH, IBGIB_DNA_SUBPATH, IBGIB_ENCODING, IBGIB_IBGIBS_SUBPATH, IBGIB_META_SUBPATH } from '../../../witness/space/filesystem-space/filesystem-constants.mjs';
-import { DEFAULT_ENCRYPTION_HASH_ALGORITHM, DEFAULT_ENCRYPTION_INITIAL_RECURSIONS, DEFAULT_ENCRYPTION_RECURSIONS_PER_HASH, DEFAULT_ENCRYPTION_SALT_STRATEGY, ENCRYPTION_REL8N_NAME, SECRET_REL8N_NAME } from '../../../common/encrypt/encrypt-constants.mjs';
+import { DEFAULT_ENCRYPTION_HASH_ALGORITHM, DEFAULT_ENCRYPTION_INITIAL_RECURSIONS, DEFAULT_ENCRYPTION_RECURSIONS_PER_HASH, DEFAULT_ENCRYPTION_SALT_STRATEGY, ENCRYPTION_REL8N_NAME, } from '../../../common/encrypt/encrypt-constants.mjs';
 import { ROBBOT_REL8N_NAME } from '../../../witness/robbot/robbot-constants.mjs';
 import { APP_REL8N_NAME } from '../../../witness/app/app-constants.mjs';
 import { AUTOSYNC_ALWAYS_REL8N_NAME } from '../../../common/other/other-constants.mjs';
@@ -65,12 +64,15 @@ import {
 } from './metaspace-types.mjs';
 import { MetaspaceService, TempCacheEntry } from './metaspace-types.mjs';
 import { InnerSpace_V1 } from '../../../witness/space/inner-space/inner-space-v1.mjs';
+
 import { GLOBAL_LOG_A_LOT, GLOBAL_TIMER_NAME } from '../../../core-constants.mjs';
 import { newupSubject } from '../../../common/pubsub/subject/subject-helper.mjs';
 import { ObservableWitness, } from '../../../common/pubsub/observable/observable-types.mjs';
 import { SubjectWitness } from '../../../common/pubsub/subject/subject-types.mjs';
 import { SubscriptionWitness } from '../../../common/pubsub/subscription/subscription-types.mjs';
 import { fnObs } from '../../../common/pubsub/observer/observer-helper.mjs';
+import { SecretData_V1, SecretIbGib_V1, SecretInfo_Password } from '../../../common/secret/secret-types.mjs';
+import { SECRET_REL8N_NAME } from '../../../common/secret/secret-constants.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -2297,6 +2299,7 @@ export abstract class MetaspaceBase implements MetaspaceService {
         createIfNone,
         dontPrompt,
         space,
+        outerspaceIds,
         fnSpaceFactory,
         fnPromptSecret,
         fnPromptEncryption,
@@ -2312,6 +2315,10 @@ export abstract class MetaspaceBase implements MetaspaceService {
          */
         dontPrompt?: boolean,
         space?: IbGibSpaceAny,
+        /**
+         * @see {@link syncIbGibs} arg of the same name
+         */
+        outerspaceIds?: SpaceId[],
         fnSpaceFactory: (unencryptedSpaceData: any) => Promise<IbGibSpaceAny>,
         fnPromptSecret: (space: IbGibSpaceAny) => Promise<SecretIbGib_V1 | undefined>,
         fnPromptEncryption: (space: IbGibSpaceAny) => Promise<EncryptionIbGib | undefined>,
@@ -2333,20 +2340,31 @@ export abstract class MetaspaceBase implements MetaspaceService {
                     space,
                 });
 
+            // filter if applicable
+            const hasOuterspaceIds = (outerspaceIds?.length ?? 0) > 0;
+            if (hasOuterspaceIds) {
+                appSyncSpaces = appSyncSpaces.filter(x => outerspaceIds!.includes(x.data!.uuid!));
+            }
+
             // create if applicable
-            if (appSyncSpaces.length === 0 && createIfNone) {
-                const createdReqs = await this._createOuterspaceAndRequiredIbGibs({
-                    space,
-                    fnPromptSecret,
-                    fnPromptEncryption,
-                    fnPromptOuterSpace,
-                });
-                if (createdReqs) {
-                    appSyncSpaces = await this.getSpecialRel8dIbGibs<IbGibSpaceAny>({
-                        type: "outerspaces",
-                        rel8nName: SYNC_SPACE_REL8N_NAME,
+            if (appSyncSpaces.length === 0) {
+                if (createIfNone) {
+                    if (hasOuterspaceIds) { throw new Error(`(UNEXPECTED) both createIfNone true and outerspaceIds (filter) also true? you cannot have both of these set, it's one of the other. (E: 9caaa121dee3e41e6e29916614cd4e24)`); }
+                    const createdReqs = await this._createOuterspaceAndRequiredIbGibs({
                         space,
+                        fnPromptSecret,
+                        fnPromptEncryption,
+                        fnPromptOuterSpace,
                     });
+                    if (createdReqs) {
+                        appSyncSpaces = await this.getSpecialRel8dIbGibs<IbGibSpaceAny>({
+                            type: "outerspaces",
+                            rel8nName: SYNC_SPACE_REL8N_NAME,
+                            space,
+                        });
+                    }
+                } else {
+                    throw new Error(`No sync spaces found. First create a sync outerspace (like a cloud sync space) in order to synchronize with it (E: 8f395f226ac7b558b9317befefbcb724)`);
                 }
             }
 
@@ -2554,6 +2572,7 @@ export abstract class MetaspaceBase implements MetaspaceService {
         dependencyGraphIbGibs,
         // confirm,
         watch,
+        outerspaceIds,
         fnPreSyncProgress,
         fnSpaceFactory,
         fnPromptSecret,
@@ -2567,6 +2586,11 @@ export abstract class MetaspaceBase implements MetaspaceService {
          * (tjps).
          */
         watch?: boolean,
+        /**
+         * if provided, these will determine which outerspace(s) we will sync
+         * the {@link dependencyGraphIbGibs} with.
+         */
+        outerspaceIds?: SpaceId[],
         /**
          * The meat of the sync process is tracked via a status within the sync
          * spaces themselves. I'm addign this fn to track the pre and post progress
@@ -2640,6 +2664,7 @@ export abstract class MetaspaceBase implements MetaspaceService {
                 unwrapEncrypted: true,
                 createIfNone: true,
                 space: localUserSpace,
+                outerspaceIds,
                 fnSpaceFactory,
                 fnPromptSecret,
                 fnPromptEncryption,
@@ -2648,14 +2673,14 @@ export abstract class MetaspaceBase implements MetaspaceService {
             if (fnPreSyncProgress) { fnPreSyncProgress('build complete. (I: 391a9aa7749d45b1aecf9a0010d9937f)'); }
             console.timeLog(syncTimelogName, 'getAppSyncSpaces starting (unwrapEncrypted is true) complete.');
             if (appSyncSpaces.length === 0) {
-                const msg = `Can't sync without sync spaces...wrong password? Cancelling. Restart app to retry password (I know it sucks!...just me coding this thing right now)`;
+                const msg = `Hmm, we seem to not have any sync spaces, and we can't exactly sync without them. Sometimes this is because of a wrong password? (I: 902bd3e00c3246abb646a750f2f2b782)`;
                 if (logalot) { console.log(`${lc} ${msg}`) };
                 const fnAlert = this.getFnAlert!();
-                await fnAlert({ title: "Cancelled", msg });
+                await fnAlert({ title: "Sync Cancelled", msg });
                 this._syncing = false;
                 console.timeLog(syncTimelogName, 'cancelled');
                 console.timeEnd(syncTimelogName);
-                return;
+                return undefined; /* <<<< returns early */
             }
             // const localUserSpace = await this.getLocalUserSpace({});
             const participants: ParticipantInfo[] = [

package/src/witness/space/metaspace/metaspace-types.mts

@@ -22,13 +22,13 @@ import { RootData } from '../../../common/root/root-types.mjs';
 import {
     CiphertextData, CiphertextIbGib_V1, CiphertextRel8ns,
     EncryptionData_V1, EncryptionIbGib, EncryptionInfo_EncryptGib,
-    SecretData_V1, SecretIbGib_V1, SecretInfo_Password
 } from '../../../common/encrypt/encrypt-types.mjs';
 import { RobbotIbGib_V1, RobbotPromptResult } from '../../../witness/robbot/robbot-types.mjs';
 import { AppIbGib_V1, AppPromptResult } from '../../../witness/app/app-types.mjs';
 import { rel8ToSpecialIbGib, } from '../../../witness/space/space-helper.mjs';
 import { GetDependencyGraphOptions } from '../../../common/other/graph-helper.mjs';
 import { ObservableWitness, ObservableWitnessAny } from '../../../common/pubsub/observable/observable-types.mjs';
+import { SecretData_V1, SecretIbGib_V1 } from '../../../common/secret/secret-types.mjs';
 
 export interface CreateLocalSpaceOptions {
     allowCancel: boolean;
@@ -572,14 +572,26 @@ export interface MetaspaceService {
         fnPromptApp: (space: IbGibSpaceAny, ibGib: AppIbGib_V1 | null) => Promise<AppPromptResult | undefined>,
         space?: IbGibSpaceAny,
     }): Promise<AppIbGib_V1[]>;
+    /**
+     * sync a dependency graph of ibgibs with one or more (external)
+     * outerspaces.
+     */
     syncIbGibs(arg: {
+        /**
+         * ibgibs to be synced.
+         */
         dependencyGraphIbGibs?: IbGib_V1[],
         // confirm?: boolean,
         /**
          * If true, will watch ibgibs in dependency graph that have timelines
-         * (tjps).
+         * (tjps) to keep in sync going forward.
          */
         watch?: boolean,
+        /**
+         * if provided, these will determine which outerspace(s) we will sync
+         * the {@link dependencyGraphIbGibs} with.
+         */
+        outerspaceIds?: SpaceId[],
         /**
          * The meat of the sync process is tracked via a status within the sync
          * spaces themselves. I'm addign this fn to track the pre and post progress

package/src/witness/space/outer-space/outer-space-types.mts

@@ -135,6 +135,9 @@ export type SyncSpaceSubtype =
     'local-machine-node';
 export const SyncSpaceSubtype = {
     aws_dynamodb: 'aws-dynamodb' as SyncSpaceSubtype,
+    /**
+     * not implemented yet
+     */
     local_machine_node: 'local-machine-node' as SyncSpaceSubtype,
 }