@noy-db/hub 0.3.0 → 0.4.0-pre.1

package/dist/with-party/directory/cover/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Cover — owner-curated plaintext metadata, readable before vault
+ * unlock or bundle decryption. Like a book's cover: title, cover
+ * art, back-cover blurb — readable on the shelf without opening
+ * the book, and never trusted as the book's contents.
+ *
+ * (Formerly "public envelope" — the wire keeps that name: the
+ * record still lives at `_meta/public-envelope` and carries the
+ * `_noydb_public: 1` discriminator.)
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md
+ *
+ * @module
+ */
+/**
+ * Either a single string (used when the developer's app is
+ * single-locale) or a locale → string map for i18n. Mirrors the
+ * shape `@noy-db/hub/i18n` already uses for record fields, so the
+ * existing `resolveI18nText` resolver applies.
+ */
+export type CoverText = string | Record<string, string>;
+/**
+ * A JSON-serializable value — what a `custom` namespace payload may
+ * hold. No functions, `undefined`, symbols, bigints, or cycles; the
+ * validator additionally caps nesting depth at 8 levels.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Persisted shape — both `_meta/public-envelope` (the frozen wire
+ * name) and the bundle header carry this. The version number is
+ * monotonic per vault and helps cache invalidators detect change
+ * without hashing the JSON.
+ */
+export interface Cover {
+    readonly _noydb_public: 1;
+    readonly version: number;
+    readonly name?: CoverText;
+    readonly description?: CoverText;
+    /** Inline `data:` URL (`data:image/png;base64,…` or `data:image/svg+xml;base64,…`). */
+    readonly icon?: string;
+    /** ISO-8601 timestamp; auto-set on first cover write, immutable thereafter. */
+    readonly createdAt?: string;
+    /** ISO-8601 timestamp; auto-updated on every `setCover` call. */
+    readonly updatedAt?: string;
+    /** BCP-47 fallback locale for renderers when the user's locale isn't covered. */
+    readonly defaultLocale?: string;
+    /**
+     * Namespaced integrator slot (#800) — e.g.
+     * `{ 'noydb.viewer': { defaultCollection: 'invoices' } }`. Keys must
+     * be reverse-DNS / package-style (`noydb.viewer`, `com.acme.registry`).
+     * Like everything on the cover it is plaintext, public, and
+     * unauthenticated — payloads are hints, never authority. Opt-in:
+     * excluded from `DEFAULT_COVER_SCHEMA.fields`, so `cover: true`
+     * does NOT enable it.
+     */
+    readonly custom?: Record<string, JsonValue>;
+}
+/** Field names the developer can allow in `CoverSchema.fields`. */
+export declare const COVER_FIELDS: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale", "custom"];
+export type CoverField = (typeof COVER_FIELDS)[number];
+/**
+ * Build-time schema. The developer enables the feature and bounds
+ * what the owner can set. `true` is shorthand for "all defaults" —
+ * gives the owner the full field set with the standard caps.
+ */
+export interface CoverSchema {
+    /**
+     * Allowed field names. Setting `name`/`description`/`icon`/`defaultLocale` is
+     * gated on the field being listed here. `createdAt` / `updatedAt` are managed
+     * by the hub; including them is a no-op (the owner cannot set them
+     * directly). Default: every field above.
+     */
+    readonly fields?: ReadonlyArray<CoverField>;
+    /**
+     * Maximum icon size — measured as the length of the data-URL
+     * string. Default 256 KB.
+     */
+    readonly maxIconBytes?: number;
+    /** Allowed icon MIME types. Default ['image/png', 'image/svg+xml']. */
+    readonly iconMimeTypes?: ReadonlyArray<string>;
+    /** Maximum length of `name` / `description` per locale. Default 200. */
+    readonly maxStringChars?: number;
+    /**
+     * Maximum serialized size (`JSON.stringify` length) of the whole
+     * would-be-persisted `custom` object, measured AFTER the namespace
+     * patch merge. Default 8 KB.
+     */
+    readonly maxCustomBytes?: number;
+    /**
+     * Maximum serialized size of the ENTIRE would-be-persisted cover
+     * document. The consumer-protection cap — bounds what a pre-auth
+     * reader must fetch and parse, and closes the unbounded locale-map
+     * key-count hole for `name` / `description`. Default 300 KB
+     * (headroom over the 256 KB icon cap + text fields).
+     */
+    readonly maxCoverBytes?: number;
+}
+/**
+ * Default schema values; merged onto every developer-supplied schema.
+ * NOTE: `fields` is the six display fields, deliberately NOT
+ * {@link COVER_FIELDS} — the opt-in `'custom'` slot is excluded, so
+ * the `cover: true` shorthand never exposes it by accident.
+ */
+export declare const DEFAULT_COVER_SCHEMA: {
+    readonly fields: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale"];
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: readonly ["image/png", "image/svg+xml"];
+    readonly maxStringChars: 200;
+    readonly maxCustomBytes: number;
+    readonly maxCoverBytes: number;
+};
+/** Resolved schema after merging developer override onto defaults. */
+export interface ResolvedCoverSchema {
+    readonly fields: ReadonlyArray<CoverField>;
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: ReadonlyArray<string>;
+    readonly maxStringChars: number;
+    readonly maxCustomBytes: number;
+    readonly maxCoverBytes: number;
+}
+/**
+ * Merge developer schema onto the defaults. The shorthand `true`
+ * resolves to the full default schema; an explicit object only
+ * overrides the keys it provides.
+ */
+export declare function resolveSchema(schema: true | CoverSchema | undefined): ResolvedCoverSchema | undefined;
+/** @deprecated Use {@link Cover}. */
+export type PublicEnvelope = Cover;
+/** @deprecated Use {@link CoverText}. */
+export type PublicEnvelopeText = CoverText;
+/** @deprecated Use {@link CoverField}. */
+export type PublicEnvelopeField = CoverField;
+/** @deprecated Use {@link CoverSchema}. */
+export type PublicEnvelopeSchema = CoverSchema;
+/** @deprecated Use {@link ResolvedCoverSchema}. */
+export type ResolvedPublicEnvelopeSchema = ResolvedCoverSchema;
+/** @deprecated Use {@link COVER_FIELDS}. */
+export declare const PUBLIC_ENVELOPE_FIELDS: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale", "custom"];
+/** @deprecated Use {@link DEFAULT_COVER_SCHEMA}. */
+export declare const DEFAULT_PUBLIC_ENVELOPE_SCHEMA: {
+    readonly fields: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale"];
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: readonly ["image/png", "image/svg+xml"];
+    readonly maxStringChars: 200;
+    readonly maxCustomBytes: number;
+    readonly maxCoverBytes: number;
+};

package/dist/with-party/team/noydb-facade.d.ts

@@ -161,7 +161,7 @@ export declare class TeamFacade {
      * ```
      *
      * Returns the WebAuthn `credentialId` (extracted from `meta.credentialId`)
-     * for the caller's lookup index (a bootstrap vault, a PublicEnvelope,
+     * for the caller's lookup index (a bootstrap vault, a Cover,
      * a server-side allowlist).
      *
      * Gated by `enroll-authenticator` like `enrollAuthenticator()` itself.

package/dist/with-party/team/sync-period-scope.d.ts

@@ -0,0 +1,78 @@
+/**
+ * #807 — period-scoped pull support for the `SyncEngine` (thin-client
+ * bootstrap: first sync pulls the current period + the period summaries;
+ * historical periods backfill on demand via `pull({ periods: ['<name>'] })`).
+ *
+ * ## Membership law
+ *
+ * The engine only ever sees ciphertext envelopes, so period membership at
+ * the sync tier is by write-time `_ts` against the closed periods' windows
+ * (`periodExclusiveUpperBound`) — the SAME store-tier law freeze (#604) and
+ * archive (#613) use, NOT the business-date (`dateField`) seal the write
+ * guard applies inside the trust boundary. A late-booked record (in-period
+ * business date, current write-time) therefore syncs with the current
+ * period — mirroring how it archives at the NEXT period's archive.
+ *
+ * Closed periods partition the timeline by their exclusive upper bounds:
+ * the earliest closed period's window is unbounded below (a close seals
+ * everything at-or-before its `endDate`), each later one starts at its
+ * predecessor's bound, and the CURRENT window is everything at-or-after
+ * the latest closed bound (everything, when no period was ever closed).
+ *
+ * ## What a period filter can never drop
+ *
+ * - **Period summaries** (`_periods` + freeze/archive/target-purge
+ *   companions) — the navigation index; always pulled in full, exempt from
+ *   every filter (`collections`, `periods`, `modifiedSince`).
+ * - **Delete markers and tombstones** — an erasure or delete must never be
+ *   skipped by partial sync (the #589/#590 law, mirroring the
+ *   `modifiedSince` exemption). This is what makes a device that never
+ *   pulled period P converge instead of resurrecting P's deleted records
+ *   when it later backfills.
+ * - **Reserved lookups** (`_dict_*`/`_lookup_*`) — vocabulary/config rows
+ *   are not period-partitioned data; their explicit pull loop is exempt.
+ *
+ * Push is NEVER period-filtered — `PushOptions` has no `periods` member at
+ * all; a thin client's writes always flow up in full.
+ */
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+import { PERIODS_COLLECTION } from '../../with-audit/periods/window.js';
+export { PERIODS_COLLECTION };
+/**
+ * The reserved period-metadata collections a period-scoped pull always
+ * fetches first (phase 1, "summaries"): the hash-chained `_periods` index
+ * plus its freeze/archive/target-purge companions.
+ */
+export declare const PERIOD_SUMMARY_COLLECTIONS: readonly string[];
+/** The subset of a decrypted `PeriodRecord` the window computation needs. */
+export interface PeriodSyncRecord {
+    readonly name: string;
+    readonly kind: 'closed' | 'opened';
+    readonly endDate: string;
+}
+/**
+ * Vault-injected source of decrypted period records, wired via
+ * `SyncEngine.setPeriodPullSource` (same injection pattern as
+ * `setReservedLookupSource`). MUST re-read from the local store on every
+ * call — the engine invokes it right after the summaries phase applied
+ * freshly pulled `_periods` envelopes.
+ */
+export interface PeriodPullSource {
+    periods(): Promise<readonly PeriodSyncRecord[]>;
+}
+/** Validate the raw `PullOptions.periods` value (runtime shape only). */
+export declare function validatePeriodsOption(periods: unknown): asserts periods is readonly string[] | {
+    readonly current: true;
+};
+/**
+ * Resolve the selected `_ts` windows and return the pull-scope predicate:
+ * `true` = the envelope is in scope for this pull. Tombstones and delete
+ * markers are unconditionally in scope (see module doc).
+ *
+ * Throws `ValidationError` for a name that is not a closed period in the
+ * (freshly synced) `_periods` index — a typo'd backfill must fail loudly,
+ * never silently pull nothing.
+ */
+export declare function buildPeriodScope(option: readonly string[] | {
+    readonly current: true;
+}, records: readonly PeriodSyncRecord[]): (envelope: EncryptedEnvelope) => boolean;

package/dist/with-party/team/sync.d.ts

@@ -1,4 +1,5 @@
 import type { NoydbStore, DirtyEntry, ConflictStrategy, CollectionConflictResolver, PushOptions, PullOptions, PushResult, PullResult, SyncStatus, SyncTargetRole } from '../../kernel/types.js';
+import { type PeriodPullSource } from './sync-period-scope.js';
 import type { NoydbEventEmitter } from '../../kernel/events.js';
 import type { SyncPolicy } from '../../kernel/sync-policy.js';
 import { SyncScheduler } from '../../kernel/sync-policy.js';
@@ -66,6 +67,18 @@ export declare class SyncEngine {
     private reservedDictExpander?;
     /** Wire the reserved-dict expansion function (#653). Same injection pattern as `setPairExpander`. */
     setReservedDictExpander(expander: (names: readonly string[]) => readonly string[]): void;
+    /** #807: vault-injected source of decrypted period records — resolves the `_ts` windows a
+     *  `pull({ periods })` scopes to. Re-read AFTER the summaries phase, so a fresh device's
+     *  freshly pulled `_periods` index is what the windows are computed from. `undefined` on a
+     *  standalone engine that was never vault-attached (period-scoped pull then throws). */
+    private periodPullSource?;
+    /** Wire the period-window source (#807). Same injection pattern as `setReservedLookupSource`. */
+    setPeriodPullSource(source: PeriodPullSource): void;
+    /** #807: KPI accumulator `applyRemote` feeds during a period-scoped `pull()` — pointed at the
+     *  active phase's counters (summaries → records) and cleared before pull returns. Approximate
+     *  by design: a push interleaved mid-pull on the same engine would attribute its converge
+     *  applies to the open phase; the counters are a download-budget KPI, not an audit source. */
+    private pullByteSink;
     constructor(opts: {
         local: NoydbStore;
         remote: NoydbStore;

package/dist/with-pod/bundle.d.ts

@@ -35,7 +35,7 @@
 import { type NoydbPodHeader } from './format.js';
 import type { Vault } from '../kernel/vault.js';
 import type { BundleRecipient } from '../with-party/team/keyring.js';
-import type { PublicEnvelope } from '../with-party/directory/public-envelope/types.js';
+import type { Cover } from '../with-party/directory/cover/types.js';
 import type { SealingKeyProvider, RecipientSealer, RecipientHint } from '../with-party/team/managed-passphrase.js';
 /**
  * The credential kinds that can be bundled for auto-unlock.
@@ -376,21 +376,23 @@ export declare function readPodHeader(bytes: Uint8Array): NoydbPodHeader;
 /** @deprecated Use `readPodHeader`. */
 export declare const readNoydbBundleHeader: typeof readPodHeader;
 /**
- * Read just the bundle's public envelope (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`)
+ * Read just the bundle's cover (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`)
  * — without verifying the body or even parsing the dump JSON. Pass
  * the raw bundle bytes; receive the owner-curated metadata or
  * `undefined` if the bundle was written without one.
  *
  * Locale-resolves any `name` / `description` map fields when `locale`
- * is supplied. Omitting `locale` returns the raw envelope.
+ * is supplied. Omitting `locale` returns the raw cover.
  *
- * Same security caveat as the on-vault read path — the public
- * envelope is **untrusted hint** in v1; the encrypted body remains
+ * Same security caveat as the on-vault read path — the cover is an
+ * **untrusted hint** in v1; the encrypted body remains
  * the source of truth for vault contents.
  */
-export declare function readNoydbBundlePublicEnvelope(bytes: Uint8Array, opts?: {
+export declare function readPodCover(bytes: Uint8Array, opts?: {
     readonly locale?: string;
-}): PublicEnvelope | undefined;
+}): Cover | undefined;
+/** @deprecated Use `readPodCover` (#799 rename). */
+export declare const readNoydbBundlePublicEnvelope: typeof readPodCover;
 /**
  * Read a full `.noydb` bundle: validate magic + header, verify
  * integrity hash over the body bytes, decompress, and return the

package/dist/with-pod/format.d.ts

@@ -45,7 +45,7 @@
  * carries only what's needed to identify the file as a NOYDB
  * bundle and verify its integrity — nothing about the contents.
  */
-import type { PublicEnvelope } from '../with-party/directory/public-envelope/types.js';
+import type { Cover } from '../with-party/directory/cover/types.js';
 /** Magic bytes 'NDB1' (ASCII), identifying a NOYDB bundle. */
 export declare const NOYDB_BUNDLE_MAGIC: Uint8Array<ArrayBuffer>;
 /** Total fixed prefix before the header JSON: 4+1+1+4 bytes. */
@@ -110,17 +110,21 @@ export interface NoydbPodHeader {
     /** SHA-256 of the compressed body bytes (lowercase hex). Lets readers verify integrity without decompressing. */
     readonly bodySha256: string;
     /**
-     * Owner-curated public envelope (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`).
+     * Owner-curated cover (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`).
      * Optional — present only when the source vault has a
      * `_meta/public-envelope` document AND the writer's hub is opted
      * into the feature. Treat as **untrusted hint**; the body's
      * encrypted contents remain the source of truth.
      *
-     * The envelope deliberately widens the minimum-disclosure rule
+     * The JSON key keeps its frozen wire name `publicEnvelope` (#799
+     * renamed only the developer surface — existing bundles stay
+     * readable byte-for-byte).
+     *
+     * The cover deliberately widens the minimum-disclosure rule
      * for explicit, owner-curated label fields (name, icon, …). Every
      * other unknown header key still rejects at parse time.
      */
-    readonly publicEnvelope?: PublicEnvelope;
+    readonly publicEnvelope?: Cover;
     /**
      * Auto-unlock material indicator. When present, the bundle
      * body wraps the dump JSON in a structure carrying per-user

package/dist/with-pod/index.d.ts

@@ -11,7 +11,8 @@
  * omit this subpath and save ~805 LOC of format code + Brotli/gzip
  * wiring.
  */
-export { writePod, readPod, readPodHeader, writeNoydbBundle, readNoydbBundle, readNoydbBundleHeader, resetBrotliSupportCache, } from './bundle.js';
+export { writePod, readPod, readPodHeader, readPodCover, writeNoydbBundle, readNoydbBundle, readNoydbBundleHeader, resetBrotliSupportCache, } from './bundle.js';
+export type { Cover } from '../with-party/directory/cover/types.js';
 export type { WritePodOptions, WriteNoydbBundleOptions, ReadNoydbBundleOptions, NoydbBundleReadResult, } from './bundle.js';
 export { NOYDB_BUNDLE_MAGIC, NOYDB_BUNDLE_PREFIX_BYTES, NOYDB_BUNDLE_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validateBundleHeader, encodeBundleHeader, } from './format.js';
 export type { CompressionAlgo, NoydbPodHeader, NoydbBundleHeader, } from './format.js';

package/dist/withdraw-accessible-Y3B2535F.js

@@ -0,0 +1,28 @@
+import {
+  FROZEN_SNAPSHOTS_COLLECTION,
+  freezeAndDeleteClosure,
+  freezeSnapshotOnly,
+  randomId,
+  withdrawAccessibleData
+} from "./chunk-YJV2UZ7H.js";
+import "./chunk-GQNGCEP5.js";
+import "./chunk-A7JJLVGH.js";
+import "./chunk-J6Q7UVQE.js";
+import "./chunk-DVUZMT2W.js";
+import "./chunk-WEYZTLXN.js";
+import "./chunk-IY23KFNZ.js";
+import "./chunk-N6WF5PKC.js";
+import "./chunk-6HY2X62D.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-HOONYZY2.js";
+import "./chunk-LSASLXGC.js";
+import "./chunk-W2OG6JOL.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  FROZEN_SNAPSHOTS_COLLECTION,
+  freezeAndDeleteClosure,
+  freezeSnapshotOnly,
+  randomId,
+  withdrawAccessibleData
+};
+//# sourceMappingURL=withdraw-accessible-Y3B2535F.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/hub",
-  "version": "0.3.0",
+  "version": "0.4.0-pre.1",
   "description": "Zero-knowledge, offline-first, encrypted document store — core library with AES-256-GCM, PBKDF2, multi-user keyring, and sync engine",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -120,6 +120,10 @@
       "types": "./dist/kernel/util/index.d.ts",
       "default": "./dist/util/index.js"
     },
+    "./share-link": {
+      "types": "./dist/share-link/index.d.ts",
+      "default": "./dist/share-link/index.js"
+    },
     "./attestation": {
       "types": "./dist/with-audit/attestation/index.d.ts",
       "default": "./dist/attestation/index.js"
@@ -192,14 +196,14 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@noy-db/attestation": "0.3.0"
+    "@noy-db/attestation": "0.4.0-pre.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.25.0",
     "zod": "^4.0.0",
     "zod-to-json-schema": "^3.25.2",
-    "@noy-db/on-shamir": "0.3.0"
+    "@noy-db/on-shamir": "0.4.0-pre.1"
   },
   "peerDependencies": {
     "zod-to-json-schema": "^3.25.0"

package/dist/api-ZGS6LCOF.js

@@ -1,20 +0,0 @@
-import {
-  UserApi,
-  createUserApi
-} from "./chunk-LASZKVMO.js";
-import "./chunk-4JBYV75E.js";
-import "./chunk-XDYREZWE.js";
-import "./chunk-7DSTRQIJ.js";
-import "./chunk-HB3RFQSC.js";
-import "./chunk-JKJOGPZN.js";
-import "./chunk-5M5DVGV7.js";
-import "./chunk-LP7BEXCT.js";
-import "./chunk-CIE2BASH.js";
-import "./chunk-JNAI2HN2.js";
-import "./chunk-BIOUI4HL.js";
-import "./chunk-PZ5AY32C.js";
-export {
-  UserApi,
-  createUserApi
-};
-//# sourceMappingURL=api-ZGS6LCOF.js.map