cursedbelt-core 2.2.0 → 2.3.0

package/dist/config/appConfig.d.ts

@@ -1,7 +1,7 @@
 /**
  * `app-config.json` — the single schema the compiler AND the runtime import
  * (02-MASTER-ENGINES §2). Nothing else may re-declare this shape: a second copy
- * is how `privateMedia` without `guard` parsed as valid for a year (J2-1).
+ * is how a feature without the engine it needs parsed as valid for a year (J2-1).
  *
  * Two laws are encoded here rather than in prose:
  *
@@ -9,8 +9,8 @@
  *    `features` block — is a parse ERROR (`unknown-config-key`), never silently
  *    stripped. A typo'd flag that gets dropped reads as "the feature is off" at
  *    runtime, which is indistinguishable from a bug in the feature.
- * 2. `.superRefine()` cross-engine dependencies. `privateMedia` needs `guard`,
- *    `oralHistory` needs `asset`, `auth.enabled` needs `guard`, and the saas
+ * 2. `.superRefine()` cross-engine dependencies. `oralHistory` needs `asset`,
+ *    `auth.enabled` needs `guard`, and the saas
  *    profile needs `guard` + `rbac:true`. These are structural: the config
  *    references something that will not exist at runtime, so it dies at V0 —
  *    fail-closed on structure (04 §0).
@@ -41,7 +41,6 @@ export declare const AssetFeatures: z.ZodObject<{
     editor: z.ZodDefault<z.ZodBoolean>;
     fileBrowser: z.ZodDefault<z.ZodBoolean>;
     taggedFiles: z.ZodDefault<z.ZodBoolean>;
-    privateMedia: z.ZodDefault<z.ZodBoolean>;
     vaultSource: z.ZodDefault<z.ZodBoolean>;
     ocr: z.ZodDefault<z.ZodBoolean>;
     imageStudio: z.ZodDefault<z.ZodBoolean>;
@@ -127,7 +126,6 @@ export declare const FeaturesByEngine: {
         editor: z.ZodDefault<z.ZodBoolean>;
         fileBrowser: z.ZodDefault<z.ZodBoolean>;
         taggedFiles: z.ZodDefault<z.ZodBoolean>;
-        privateMedia: z.ZodDefault<z.ZodBoolean>;
         vaultSource: z.ZodDefault<z.ZodBoolean>;
         ocr: z.ZodDefault<z.ZodBoolean>;
         imageStudio: z.ZodDefault<z.ZodBoolean>;

package/dist/config/appConfig.js

@@ -1,7 +1,7 @@
 /**
  * `app-config.json` — the single schema the compiler AND the runtime import
  * (02-MASTER-ENGINES §2). Nothing else may re-declare this shape: a second copy
- * is how `privateMedia` without `guard` parsed as valid for a year (J2-1).
+ * is how a feature without the engine it needs parsed as valid for a year (J2-1).
  *
  * Two laws are encoded here rather than in prose:
  *
@@ -9,8 +9,8 @@
  *    `features` block — is a parse ERROR (`unknown-config-key`), never silently
  *    stripped. A typo'd flag that gets dropped reads as "the feature is off" at
  *    runtime, which is indistinguishable from a bug in the feature.
- * 2. `.superRefine()` cross-engine dependencies. `privateMedia` needs `guard`,
- *    `oralHistory` needs `asset`, `auth.enabled` needs `guard`, and the saas
+ * 2. `.superRefine()` cross-engine dependencies. `oralHistory` needs `asset`,
+ *    `auth.enabled` needs `guard`, and the saas
  *    profile needs `guard` + `rbac:true`. These are structural: the config
  *    references something that will not exist at runtime, so it dies at V0 —
  *    fail-closed on structure (04 §0).
@@ -31,7 +31,9 @@ export const AssetFeatures = z
     editor: z.boolean().default(false), // lazy chunk; joins bundleKey
     fileBrowser: z.boolean().default(false),
     taggedFiles: z.boolean().default(false),
-    privateMedia: z.boolean().default(false), // requires guard engine — enforced in superRefine
+    // `privateMedia` was here until 2.3.0 (task 330). Its server module and the `pfs/` keyspace
+    // were deleted from cursedbelt-server in 4.0.0, so the flag named a tier that no longer
+    // exists; `.strict()` now refuses it as `unknown-config-key`, which is the honest answer.
     vaultSource: z.boolean().default(false),
     ocr: z.boolean().default(false),
     imageStudio: z.boolean().default(false),
@@ -277,8 +279,6 @@ export const AppConfigSchema = z
         }
         const f = parsed.data;
         // (c) cross-engine dependencies — hard blocks, not comments (J2-1)
-        if (inst.engine === 'asset' && f.privateMedia === true && !engineSet.has('guard'))
-            issue(['instances', i, 'features', 'privateMedia'], `'privateMedia' requires the 'guard' engine in engines[] (engine-dependency-missing).`);
         if (inst.engine === 'knowledge' && f.oralHistory === true && !engineSet.has('asset'))
             issue(['instances', i, 'features', 'oralHistory'], `'oralHistory' requires the 'asset' engine for its media player tier (engine-dependency-missing).`);
     });

package/dist/core/passwordPolicy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The one place a satellite's owner-password floor is decided.
+ *
+ * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
+ * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
+ * a paragraph in each explaining itself against the others. A floor is a
+ * POLICY, and a policy copied three times is three policies.
+ *
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
+ * owner wants for an ordinary satellite: long enough that it is not a PIN, short
+ * enough that it does not push the owner toward writing it down or reusing one.
+ * Argon2id — what every caller hashes with — is what actually carries the cost
+ * of a guess here; these apps have exactly ONE principal and no enumerable user
+ * list, so the marginal value of characters 10–14 is small and the friction is
+ * not.
+ *
+ * ── `cursedbelt-core/password-policy`, since 2.3.0 (task 321) ────────────────
+ * The floor that exists so it cannot drift was itself copied — `src/kit/passwordPolicy.ts`
+ * in `auth`, `patterns` and `vault`. It is here, in the isomorphic tier, because `vault`
+ * enforces it in the BROWSER (`src/crypto/vaultCipher.ts`) as well as on the server, and a
+ * floor checked in two runtimes must be one import in both. It imports nothing.
+ *
+ * ── Raising it is an APP's decision, and it is the only direction ───────────
+ * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
+ * go below the default**. An app that genuinely runs at higher stakes says so
+ * at its own call site, in one visible argument, with a comment saying why.
+ * No app overrides it today — the retired orch companion app did (14, as the single
+ * internet-facing door into the host that runs `claude` in every repo) until
+ * the owner dropped it to the shared floor on 2026-07-26.
+ *
+ * The asymmetry is the whole point: a shared default can be raised locally
+ * where the risk is local, but nothing can quietly lower the floor for
+ * everyone — which is exactly the mistake a bare exported constant invites.
+ */
+/**
+ * The floor, in BYTES as typed (not codepoints — callers measure the raw bytes
+ * they read, so a multi-byte character counts as more than one, which is the
+ * conservative direction).
+ */
+export declare const DEFAULT_MIN_PASSWORD_BYTES = 9;
+/**
+ * The floor this app enforces: the default, or a higher one it asks for.
+ *
+ * Throws on an override below the default rather than silently clamping. A
+ * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * how a security floor becomes folklore.
+ */
+export declare function resolveMinPasswordBytes(override?: number): number;

package/dist/core/passwordPolicy.js

@@ -0,0 +1,60 @@
+/**
+ * The one place a satellite's owner-password floor is decided.
+ *
+ * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
+ * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
+ * a paragraph in each explaining itself against the others. A floor is a
+ * POLICY, and a policy copied three times is three policies.
+ *
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
+ * owner wants for an ordinary satellite: long enough that it is not a PIN, short
+ * enough that it does not push the owner toward writing it down or reusing one.
+ * Argon2id — what every caller hashes with — is what actually carries the cost
+ * of a guess here; these apps have exactly ONE principal and no enumerable user
+ * list, so the marginal value of characters 10–14 is small and the friction is
+ * not.
+ *
+ * ── `cursedbelt-core/password-policy`, since 2.3.0 (task 321) ────────────────
+ * The floor that exists so it cannot drift was itself copied — `src/kit/passwordPolicy.ts`
+ * in `auth`, `patterns` and `vault`. It is here, in the isomorphic tier, because `vault`
+ * enforces it in the BROWSER (`src/crypto/vaultCipher.ts`) as well as on the server, and a
+ * floor checked in two runtimes must be one import in both. It imports nothing.
+ *
+ * ── Raising it is an APP's decision, and it is the only direction ───────────
+ * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
+ * go below the default**. An app that genuinely runs at higher stakes says so
+ * at its own call site, in one visible argument, with a comment saying why.
+ * No app overrides it today — the retired orch companion app did (14, as the single
+ * internet-facing door into the host that runs `claude` in every repo) until
+ * the owner dropped it to the shared floor on 2026-07-26.
+ *
+ * The asymmetry is the whole point: a shared default can be raised locally
+ * where the risk is local, but nothing can quietly lower the floor for
+ * everyone — which is exactly the mistake a bare exported constant invites.
+ */
+/**
+ * The floor, in BYTES as typed (not codepoints — callers measure the raw bytes
+ * they read, so a multi-byte character counts as more than one, which is the
+ * conservative direction).
+ */
+export const DEFAULT_MIN_PASSWORD_BYTES = 9;
+/**
+ * The floor this app enforces: the default, or a higher one it asks for.
+ *
+ * Throws on an override below the default rather than silently clamping. A
+ * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * how a security floor becomes folklore.
+ */
+export function resolveMinPasswordBytes(override) {
+    if (override === undefined)
+        return DEFAULT_MIN_PASSWORD_BYTES;
+    if (!Number.isInteger(override)) {
+        throw new Error(`minPasswordBytes must be an integer, got ${override}`);
+    }
+    if (override < DEFAULT_MIN_PASSWORD_BYTES) {
+        throw new Error(`minPasswordBytes may only be RAISED above the shared default of ` +
+            `${DEFAULT_MIN_PASSWORD_BYTES}; refusing ${override}`);
+    }
+    return override;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.2.0",
+	"version": "2.3.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
@@ -281,6 +281,12 @@
 			"source": "./src/core/palette/ShortcutRegistry.ts",
 			"import": "./dist/core/palette/ShortcutRegistry.js"
 		},
+		"./password-policy": {
+			"types": "./dist/core/passwordPolicy.d.ts",
+			"bun": "./src/core/passwordPolicy.ts",
+			"source": "./src/core/passwordPolicy.ts",
+			"import": "./dist/core/passwordPolicy.js"
+		},
 		"./session/claims": {
 			"types": "./dist/core/session/claims.d.ts",
 			"bun": "./src/core/session/claims.ts",

package/src/config/appConfig.spec.ts

@@ -51,13 +51,11 @@ describe('strictness (02 §2.2)', () => {
 });
 
 describe('cross-engine dependencies are code, not comments (J2-1)', () => {
-  it('blocks privateMedia without the guard engine', () => {
-    const config = base({ instances: [{ engine: 'asset', id: 'gallery', features: { privateMedia: true } }] });
-    expect(parse(config).success).toBe(false);
-    expect(messages(config).join(' ')).toContain("'privateMedia' requires the 'guard' engine");
-  });
-
-  it('allows privateMedia once guard is activated', () => {
+  // 🔴 `privateMedia` was the other half of this mechanism's proof until 2.3.0 (task 330). The
+  // flag is gone, so `oralHistory` → `asset` is now the ONE feature-to-engine dependency, and it
+  // is proven both ways below — blocked without its engine, allowed with it — so the
+  // `engine-dependency-missing` diagnostic keeps a failure path AND a pass path.
+  it('refuses the retired privateMedia flag as an unknown key, never silently ignores it', () => {
     const config = base({
       engines: ['asset', 'guard'],
       instances: [
@@ -65,6 +63,20 @@ describe('cross-engine dependencies are code, not comments (J2-1)', () => {
         { engine: 'guard', id: 'guard-main' },
       ],
     });
+    expect(parse(config).success).toBe(false);
+    expect(parse(config).error?.issues.map((issue) => issue.path.join('.'))).toContain(
+      'instances.0.features.privateMedia',
+    );
+  });
+
+  it('allows oralHistory once the asset engine is activated', () => {
+    const config = base({
+      engines: ['knowledge', 'asset'],
+      instances: [
+        { engine: 'knowledge', id: 'stories', features: { oralHistory: true } },
+        { engine: 'asset', id: 'player' },
+      ],
+    });
     expect(parse(config).success).toBe(true);
   });
 

package/src/config/appConfig.ts

@@ -1,7 +1,7 @@
 /**
  * `app-config.json` — the single schema the compiler AND the runtime import
  * (02-MASTER-ENGINES §2). Nothing else may re-declare this shape: a second copy
- * is how `privateMedia` without `guard` parsed as valid for a year (J2-1).
+ * is how a feature without the engine it needs parsed as valid for a year (J2-1).
  *
  * Two laws are encoded here rather than in prose:
  *
@@ -9,8 +9,8 @@
  *    `features` block — is a parse ERROR (`unknown-config-key`), never silently
  *    stripped. A typo'd flag that gets dropped reads as "the feature is off" at
  *    runtime, which is indistinguishable from a bug in the feature.
- * 2. `.superRefine()` cross-engine dependencies. `privateMedia` needs `guard`,
- *    `oralHistory` needs `asset`, `auth.enabled` needs `guard`, and the saas
+ * 2. `.superRefine()` cross-engine dependencies. `oralHistory` needs `asset`,
+ *    `auth.enabled` needs `guard`, and the saas
  *    profile needs `guard` + `rbac:true`. These are structural: the config
  *    references something that will not exist at runtime, so it dies at V0 —
  *    fail-closed on structure (04 §0).
@@ -35,7 +35,9 @@ export const AssetFeatures = z
     editor: z.boolean().default(false), // lazy chunk; joins bundleKey
     fileBrowser: z.boolean().default(false),
     taggedFiles: z.boolean().default(false),
-    privateMedia: z.boolean().default(false), // requires guard engine — enforced in superRefine
+    // `privateMedia` was here until 2.3.0 (task 330). Its server module and the `pfs/` keyspace
+    // were deleted from cursedbelt-server in 4.0.0, so the flag named a tier that no longer
+    // exists; `.strict()` now refuses it as `unknown-config-key`, which is the honest answer.
     vaultSource: z.boolean().default(false),
     ocr: z.boolean().default(false),
     imageStudio: z.boolean().default(false),
@@ -326,11 +328,6 @@ export const AppConfigSchema = z
       const f = parsed.data as Record<string, unknown>;
 
       // (c) cross-engine dependencies — hard blocks, not comments (J2-1)
-      if (inst.engine === 'asset' && f.privateMedia === true && !engineSet.has('guard'))
-        issue(
-          ['instances', i, 'features', 'privateMedia'],
-          `'privateMedia' requires the 'guard' engine in engines[] (engine-dependency-missing).`,
-        );
       if (inst.engine === 'knowledge' && f.oralHistory === true && !engineSet.has('asset'))
         issue(
           ['instances', i, 'features', 'oralHistory'],

package/src/core/passwordPolicy.spec.ts

@@ -0,0 +1,19 @@
+/**
+ * The floor may be RAISED by an app and never lowered — the asymmetry is the whole policy.
+ */
+import { describe, expect, it } from 'bun:test';
+import { DEFAULT_MIN_PASSWORD_BYTES, resolveMinPasswordBytes } from './passwordPolicy';
+
+describe('resolveMinPasswordBytes', () => {
+  it('is the shared default when an app asks for nothing', () => {
+    expect(resolveMinPasswordBytes()).toBe(DEFAULT_MIN_PASSWORD_BYTES);
+    expect(DEFAULT_MIN_PASSWORD_BYTES).toBe(9);
+  });
+  it('lets an app raise it, visibly, at its own call site', () => {
+    expect(resolveMinPasswordBytes(14)).toBe(14);
+  });
+  it('🔴 refuses to go BELOW the default, and refuses a non-integer', () => {
+    expect(() => resolveMinPasswordBytes(8)).toThrow(/may only be RAISED/);
+    expect(() => resolveMinPasswordBytes(9.5)).toThrow(/must be an integer/);
+  });
+});

package/src/core/passwordPolicy.ts

@@ -0,0 +1,63 @@
+/**
+ * The one place a satellite's owner-password floor is decided.
+ *
+ * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
+ * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
+ * a paragraph in each explaining itself against the others. A floor is a
+ * POLICY, and a policy copied three times is three policies.
+ *
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
+ * owner wants for an ordinary satellite: long enough that it is not a PIN, short
+ * enough that it does not push the owner toward writing it down or reusing one.
+ * Argon2id — what every caller hashes with — is what actually carries the cost
+ * of a guess here; these apps have exactly ONE principal and no enumerable user
+ * list, so the marginal value of characters 10–14 is small and the friction is
+ * not.
+ *
+ * ── `cursedbelt-core/password-policy`, since 2.3.0 (task 321) ────────────────
+ * The floor that exists so it cannot drift was itself copied — `src/kit/passwordPolicy.ts`
+ * in `auth`, `patterns` and `vault`. It is here, in the isomorphic tier, because `vault`
+ * enforces it in the BROWSER (`src/crypto/vaultCipher.ts`) as well as on the server, and a
+ * floor checked in two runtimes must be one import in both. It imports nothing.
+ *
+ * ── Raising it is an APP's decision, and it is the only direction ───────────
+ * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
+ * go below the default**. An app that genuinely runs at higher stakes says so
+ * at its own call site, in one visible argument, with a comment saying why.
+ * No app overrides it today — the retired orch companion app did (14, as the single
+ * internet-facing door into the host that runs `claude` in every repo) until
+ * the owner dropped it to the shared floor on 2026-07-26.
+ *
+ * The asymmetry is the whole point: a shared default can be raised locally
+ * where the risk is local, but nothing can quietly lower the floor for
+ * everyone — which is exactly the mistake a bare exported constant invites.
+ */
+
+/**
+ * The floor, in BYTES as typed (not codepoints — callers measure the raw bytes
+ * they read, so a multi-byte character counts as more than one, which is the
+ * conservative direction).
+ */
+export const DEFAULT_MIN_PASSWORD_BYTES = 9;
+
+/**
+ * The floor this app enforces: the default, or a higher one it asks for.
+ *
+ * Throws on an override below the default rather than silently clamping. A
+ * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * how a security floor becomes folklore.
+ */
+export function resolveMinPasswordBytes(override?: number): number {
+	if (override === undefined) return DEFAULT_MIN_PASSWORD_BYTES;
+	if (!Number.isInteger(override)) {
+		throw new Error(`minPasswordBytes must be an integer, got ${override}`);
+	}
+	if (override < DEFAULT_MIN_PASSWORD_BYTES) {
+		throw new Error(
+			`minPasswordBytes may only be RAISED above the shared default of ` +
+				`${DEFAULT_MIN_PASSWORD_BYTES}; refusing ${override}`,
+		);
+	}
+	return override;
+}

package/src/leafSubpathsImportNothing.spec.ts

@@ -113,6 +113,11 @@ const LEAVES = [
     /** Bundled into an app's service worker, where every byte ships on every install. */
     evaluates: 'installShellWorker',
   },
+  {
+    subpath: './password-policy',
+    /** The owner-password floor (2.3.0, task 321) — enforced in a browser bundle as well as a server. */
+    evaluates: 'resolveMinPasswordBytes',
+  },
 ] as const;
 
 /**