@noy-db/hub 0.4.0 → 0.6.0-pre.0

package/dist/with-party/team/echo-ceremony.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `beginEchoUnlock` — the interactive ceremony API (spec
+ * docs/superpowers/specs/2026-08-02-echo-secret-design.md, #940, Task 6).
+ *
+ * Split out of `echo-secret.ts` (which owns only the block builders +
+ * verifiers) because this module orchestrates BOTH `echo-secret.ts`
+ * (`verifyPrompt`/`resolveEchoReveal`/`verifyTypedEcho`) AND `keyring.ts`
+ * (`loadKeyring`) — and `keyring.ts` itself imports `buildEchoBlock` from
+ * `echo-secret.ts`. Keeping the ceremony here instead of inside
+ * `echo-secret.ts` yields a clean DAG (`echo-ceremony.ts` → {`echo-secret.ts`,
+ * `keyring.ts`}; `keyring.ts` → `echo-secret.ts`) instead of a two-file
+ * cycle, and restores `echo-secret.ts`'s documented charter (builders +
+ * verifiers only).
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { DeviceSealProvider } from './device-seal.js';
+import { type UnlockedKeyring } from './keyring.js';
+/** Options for {@link beginEchoUnlock}. */
+export interface BeginEchoUnlockOptions {
+    readonly userId: string;
+    readonly prompt: string;
+    readonly deviceSeal?: DeviceSealProvider;
+}
+/**
+ * A prompt-verified, in-progress echo unlock. Stateless w.r.t. attempts —
+ * `complete()` may be called more than once (e.g. retry after a wrong key).
+ */
+export interface EchoCeremony {
+    /**
+     * Echo to display for owner recognition; null ⇒ degraded: ask the owner to
+     * TYPE it.
+     *
+     * Conforming-player contract (spec
+     * docs/superpowers/specs/2026-08-02-echo-secret-design.md, "Ceremony"):
+     * when the owner does NOT recognize the revealed echo, the player MUST show
+     * a hard phishing warning — do not continue, open the official app, rotate
+     * the secret immediately — MUST NOT offer any skip or
+     * "verification unavailable" fallback, and MUST simply abandon the ceremony
+     * by never calling {@link EchoCeremony.complete}. The kernel cannot enforce
+     * this terminal state; it is the player's obligation.
+     */
+    readonly reveal: string | null;
+    readonly maskHint: string | undefined;
+    /** Complete the ceremony. `echo` is REQUIRED when `reveal` is null. */
+    complete(input: {
+        readonly echo?: string;
+        readonly key: string;
+    }): Promise<UnlockedKeyring>;
+}
+/**
+ * Begin the interactive anti-phishing unlock ceremony (spec decision 4):
+ * prompt → echo reveal → key. Fetches and parses the `_keyring/{userId}`
+ * row (same store path as `loadKeyring`), verifies the prompt, and resolves
+ * the echo for display (or degrades to the typed-echo path when the reveal
+ * cannot be resolved — sealed reveal under a foreign device).
+ *
+ * Conforming-player contract (spec
+ * docs/superpowers/specs/2026-08-02-echo-secret-design.md): an owner who does
+ * not recognize `ceremony.reveal` is looking at a phish. The player MUST then
+ * show a hard warning (stop, open the official app, rotate the secret now),
+ * MUST NOT offer a skip / "verification unavailable" fallback or any
+ * single-field secret entry, and MUST abandon the ceremony without calling
+ * `complete()`.
+ *
+ * @throws NoAccessError when no keyring exists for `userId` (mirrors
+ * `loadKeyring`'s missing-row error).
+ * @throws KeyringExpiredError when the slot is past its `expires_at` —
+ * checked before the prompt is verified, so an expired slot never reveals.
+ * @throws ValidationError when the keyring is not an echo keyring.
+ * @throws WrongPromptError when the prompt fails its verifier.
+ */
+export declare function beginEchoUnlock(store: NoydbStore, vault: string, opts: BeginEchoUnlockOptions): Promise<EchoCeremony>;

package/dist/with-party/team/echo-secret.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Echo-block builders + verifiers (spec
+ * docs/superpowers/specs/2026-08-02-echo-secret-design.md, #940).
+ *
+ * Builds and verifies the on-keyring {@link KeyringEchoBlock} declaration
+ * for the 3-part echo ceremony (prompt → echo → key). This module owns:
+ *
+ *   - Minting the prompt/echo canary verifiers (the "canary trick": AES-KW
+ *     wrap a constant 32-byte key under `deriveSecretKey(part, salt, …)`;
+ *     verify = unwrap succeeds).
+ *   - Building the reveal blob per the hybrid reveal policy (spec decision
+ *     4): `portable` (AES-GCM under the prompt, own salt), `sealed`
+ *     (opaque to hub, unsealed only by the enrolling device's
+ *     {@link DeviceSealProvider}), or `none`.
+ *   - Resolving the echo for display (`resolveEchoReveal`, `null` ⇒
+ *     degraded typed-echo path) and verifying a typed echo
+ *     (`verifyTypedEcho`) for that degraded path.
+ *
+ * Deriving the actual KEK from all three parts together is
+ * `deriveEchoKey`/`encodeEchoParts` (`kernel/enclave/crypto.ts`) — a
+ * separate concern from this module's per-part verifiers.
+ *
+ * Known, accepted disclosure: `prompt_verifier` and `echo_verifier` are
+ * offline brute-force oracles for anyone holding the keyring file (600K
+ * PBKDF2 per guess), and the `sealed` reveal blob is unpadded so its length
+ * discloses the echo's UTF-8 byte length — see the threat model in
+ * `docs/superpowers/specs/2026-08-02-echo-secret-design.md`.
+ *
+ * @module
+ */
+import { type EchoSecretParts } from '../../kernel/enclave/index.js';
+import type { KeyringEchoBlock } from '../../kernel/types.js';
+import type { DeviceSealProvider } from './device-seal.js';
+/** Same iteration floor as the KEK (spec resolved question 1). */
+export declare const ECHO_KDF_ITERATIONS = 600000;
+export type EchoRevealChoice = {
+    readonly kind: 'portable';
+} | {
+    readonly kind: 'sealed';
+    readonly deviceSeal: DeviceSealProvider;
+} | {
+    readonly kind: 'none';
+};
+/** Build the on-keyring echo declaration for a fresh enrollment. */
+export declare function buildEchoBlock(parts: EchoSecretParts, reveal: EchoRevealChoice, maskHint?: string): Promise<KeyringEchoBlock>;
+export declare function verifyPrompt(block: KeyringEchoBlock, prompt: string): Promise<boolean>;
+/**
+ * Resolve the echo for display. `null` ⇒ degraded path: the player
+ * must ask the owner to TYPE the echo (verify via {@link verifyTypedEcho}).
+ * Callers MUST verify the prompt first — this assumes it.
+ *
+ * @throws WrongPromptError when the prompt cannot open the portable reveal
+ * (callers should verifyPrompt first for a boolean check).
+ */
+export declare function resolveEchoReveal(block: KeyringEchoBlock, prompt: string, deviceSeal?: DeviceSealProvider): Promise<string | null>;
+export declare function verifyTypedEcho(block: KeyringEchoBlock, echo: string): Promise<boolean>;

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

@@ -32,4 +32,12 @@ export type { WrappedDeksBlob } from './wrapped-deks.js';
 export { writeMagicLinkGrant, readMagicLinkGrantRecord, listMagicLinkGrants, unwrapMagicLinkGrant, revokeMagicLinkGrant, deriveMagicLinkContentKey, magicLinkGrantRecordId, isMagicLinkGrantExpired, } from './magic-link-grant.js';
 export { hasExportCapability, evaluateExportCapability, } from './keyring.js';
 export { hasImportCapability, evaluateImportCapability, } from './keyring.js';
+export { buildEchoBlock, verifyPrompt, resolveEchoReveal, verifyTypedEcho, } from './echo-secret.js';
+export type { EchoRevealChoice } from './echo-secret.js';
+export { beginEchoUnlock } from './echo-ceremony.js';
+export type { BeginEchoUnlockOptions, EchoCeremony } from './echo-ceremony.js';
+export { MemoryDeviceSealProvider } from './device-seal.js';
+export type { DeviceSealProvider } from './device-seal.js';
+export type { EchoSecretParts } from '../../kernel/enclave/index.js';
+export type { KeyringEchoBlock, NoydbStore } from '../../kernel/types.js';
 export { describeAuthConfig, diagramAuthConfig, describeUserAuth, describeAllUsersAuth, } from '../auth-introspection/index.js';

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

@@ -1,6 +1,7 @@
-import type { NoydbStore, KeyringFile, KeyringAuthenticator, Role, Permissions, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, ExportCapability, ExportFormat, ImportCapability, VaultPolicyOnDisk, UserEnvelope } from '../../kernel/types.js';
-import { type EnclaveKey } from '../../kernel/enclave/index.js';
-import { type SecretPolicy } from '../../kernel/validation.js';
+import type { NoydbStore, KeyringFile, KeyringAuthenticator, Role, Permissions, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, EncryptedEnvelope, ExportCapability, ExportFormat, ImportCapability, VaultPolicyOnDisk, UserEnvelope } from '../../kernel/types.js';
+import { type EnclaveKey, type EchoSecretParts } from '../../kernel/enclave/index.js';
+import { type SecretPolicy, type EchoSecretPolicy } from '../../kernel/validation.js';
+import type { DeviceSealProvider } from './device-seal.js';
 /** In-memory representation of an unlocked keyring. */
 export interface UnlockedKeyring {
     readonly userId: string;
@@ -75,9 +76,34 @@ export declare function mintKeyringCanary(kek: EnclaveKey): Promise<string>;
 export interface LoadKeyringOptions {
     /** The user whose keyring to unlock. */
     readonly userId: string;
-    /** That user's secret. */
-    readonly secret: string;
+    /**
+     * That user's secret — a single string for a standard keyring, or the
+     * structured 3-part {@link EchoSecretParts} for an echo keyring (spec
+     * #940, AG-1: a single string can never unlock an echo keyring).
+     */
+    readonly secret: string | EchoSecretParts;
 }
+/**
+ * KDF dispatch for tier-1 unlock (spec #940). An echo keyring accepts
+ * ONLY structured parts (AG-1 — no single string is key-equivalent);
+ * a standard keyring accepts only a string.
+ */
+export declare function deriveKekForKeyring(file: KeyringFile, secret: string | EchoSecretParts, salt: Uint8Array): Promise<EnclaveKey>;
+/** Parse a raw keyring envelope. Single sanctioned reader of `_data` for keyring files. */
+export declare function parseKeyringEnvelope(envelope: EncryptedEnvelope): KeyringFile;
+/** Fetch + parse a user's keyring file; undefined when the row is missing. */
+export declare function readKeyringFile(store: NoydbStore, vault: string, userId: string): Promise<{
+    readonly envelope: EncryptedEnvelope;
+    readonly file: KeyringFile;
+} | undefined>;
+/**
+ * Shared expiry gate — refuse to unwrap an expired slot. Call before any
+ * KEK derivation so an expired slot doesn't leak timing on the secret.
+ * Comparison uses Date.parse → ms-since-epoch; an unparseable expires_at is
+ * treated as "no expiry" so a malformed value can't silently lock users out
+ * (it'll surface in tests).
+ */
+export declare function assertKeyringNotExpired(file: KeyringFile): void;
 /** Load and unlock a user's keyring for a vault. */
 export declare function loadKeyring(store: NoydbStore, vault: string, opts: LoadKeyringOptions): Promise<UnlockedKeyring>;
 /**
@@ -100,12 +126,34 @@ export declare function assertKeyringOpenAllowed(store: NoydbStore, vault: strin
 export interface CreateOwnerKeyringOptions extends SecretPolicy {
     /** The owner to create. */
     readonly userId: string;
-    /** The owner's secret. */
-    readonly secret: string;
+    /**
+     * The owner's secret — a plain string for a standard keyring, or the
+     * structured 3-part {@link EchoSecretParts} to enroll an echo keyring
+     * (spec #940). The shape alone selects the KDF and whether an `echo`
+     * block is written.
+     */
+    readonly secret: string | EchoSecretParts;
     /** Gate creation on the phrase-format strength rules. Default false. */
     readonly validate?: boolean;
     /** Escape hatch for fixtures and migrations — skips the strength gate. */
     readonly allowWeakSecret?: boolean;
+    /**
+     * Echo enrollment only: device-local sealer for the reveal blob. Present
+     * ⇒ `reveal: 'sealed'` (attacker-B resistance); absent ⇒ `reveal:
+     * 'portable'` (spec resolved question 4). Ignored for a string secret.
+     */
+    readonly deviceSeal?: DeviceSealProvider;
+    /** Echo enrollment only: optional display hint for the masked echo. */
+    readonly echoMaskHint?: string;
+    /**
+     * Echo enrollment only: strength-policy knobs for the 3-part secret's
+     * prompt / combined floors — the parts-path counterpart of the
+     * flattened `SecretPolicy` fields this options bag already extends
+     * (those apply to a STRING secret via `assertStrongSecret`; this
+     * applies to {@link EchoSecretParts} via `assertStrongEchoSecret`).
+     * Ignored for a string secret.
+     */
+    readonly echoSecretPolicy?: EchoSecretPolicy;
 }
 /**
  * Create the initial owner keyring for a new vault.
@@ -196,6 +244,15 @@ export interface ChangeSecretOptions extends SecretPolicy {
  * the OLD secret is not retyped.
  */
 export declare function changeSecret(store: NoydbStore, vault: string, keyring: UnlockedKeyring, opts: ChangeSecretOptions): Promise<UnlockedKeyring>;
+/**
+ * Echo-mode recipient secret (spec #940). A pod slot may embed the reveal
+ * (`'portable'`, default) or omit it (`'none'`) — `'sealed'` is
+ * live-device-only and unavailable here: `writePod` has no device context
+ * to seal the reveal blob against.
+ */
+export interface EchoRecipientSecret extends EchoSecretParts {
+    readonly reveal?: 'portable' | 'none';
+}
 /**
  * Recipient slot in a re-keyed `.noydb` bundle. Each slot becomes its
  * own keyring file inside the bundle, sealed with its own secret.
@@ -209,8 +266,13 @@ export interface BundleRecipient {
     readonly id: string;
     /** Optional display name. Defaults to `id`. */
     readonly displayName?: string;
-    /** Secret the recipient will type to unlock. */
-    readonly secret: string;
+    /**
+     * Secret the recipient will type to unlock — a plain string for a
+     * standard keyring, or the structured 3-part {@link EchoRecipientSecret}
+     * to embed an echo keyring so the anti-phishing ceremony travels with
+     * the pod (spec #940).
+     */
+    readonly secret: string | EchoRecipientSecret;
     /** Role on the destination vault. Defaults to `'viewer'`. */
     readonly role?: Role;
     /**

package/dist/with-party/team/rotate-recover.d.ts

@@ -17,13 +17,31 @@
  * @module
  */
 import type { NoydbStore } from '../../kernel/types.js';
-import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type EnclaveKey, type EchoSecretParts } from '../../kernel/enclave/index.js';
 import { type PaperRecoveryEntry } from './recovery.js';
 import type { ShamirRecoveryProvider } from './shamir-recovery-provider.js';
-import { type SecretPolicy } from '../../kernel/validation.js';
+import { type SecretPolicy, type EchoSecretPolicy } from '../../kernel/validation.js';
 import type { UnlockedKeyring } from './keyring.js';
+import type { DeviceSealProvider } from './device-seal.js';
 import type { KeyringAuthenticator } from '../../kernel/types.js';
 import type { EnrollAuthenticatorOptions } from './authenticators.js';
+/**
+ * Echo-enrollment knobs for a rotation whose NEW secret is 3-part (spec #940).
+ *
+ * Deliberately NOT exported: it is reachable structurally through
+ * {@link RotateSecretInput.echoOptions}, and exporting it would mean adding it
+ * to the team + root barrels for a type consumers never need to name.
+ */
+interface RotateEchoOptions {
+    /**
+     * Device-local sealer for the reveal blob. Present ⇒ `reveal: 'sealed'`;
+     * absent ⇒ `reveal: 'portable'`. Mirrors
+     * {@link CreateOwnerKeyringOptions.deviceSeal}.
+     */
+    readonly deviceSeal?: DeviceSealProvider;
+    /** Optional display hint for the masked echo. */
+    readonly maskHint?: string;
+}
 /**
  * Context handed to a {@link SlotRewrapCeremony} when `rotateSecret`
  * preserves a tier-2 slot. The ceremony's job is to re-derive its
@@ -65,10 +83,50 @@ export interface SlotRewrapContext {
 export type SlotRewrapCeremony = (ctx: SlotRewrapContext) => Promise<EnrollAuthenticatorOptions>;
 /** Caller payload for {@link rotateSecret}. */
 export interface RotateSecretInput {
-    readonly oldSecret: string;
-    readonly newSecret: string;
+    /**
+     * The secret currently opening the keyring — a string for a standard
+     * keyring, the 3-part {@link EchoSecretParts} for an echo one. The shape
+     * must MATCH the stored keyring: `deriveKekForKeyring` refuses a string on
+     * an echo keyring (`EchoCeremonyRequiredError`, AG-1) and parts on a
+     * standard one (`ValidationError`).
+     */
+    readonly oldSecret: string | EchoSecretParts;
+    /**
+     * The secret to rotate TO. Its shape — independent of `oldSecret`'s —
+     * decides the keyring's mode after rotation: parts enroll an `echo` block
+     * (standard→echo upgrade, or a re-mint on echo→echo), a string removes any
+     * existing one (echo→standard downgrade).
+     */
+    readonly newSecret: string | EchoSecretParts;
+    /**
+     * Strength-policy knobs applied when `newSecret` is a STRING. Ignored
+     * for 3-part {@link EchoSecretParts} — see `echoSecretPolicy` for the
+     * parts-path counterpart.
+     */
     readonly secretPolicy?: SecretPolicy;
+    /**
+     * Strength-policy knobs applied when `newSecret` is 3-part
+     * {@link EchoSecretParts} (prompt / combined floors). Ignored for a
+     * string `newSecret` — see `secretPolicy` for the string-path
+     * counterpart.
+     */
+    readonly echoSecretPolicy?: EchoSecretPolicy;
     readonly allowWeakSecret?: boolean;
+    /**
+     * Echo-enrollment knobs for the block minted when `newSecret` is 3-part.
+     * Ignored for a string `newSecret` (no block is written).
+     */
+    readonly echoOptions?: RotateEchoOptions;
+    /**
+     * Explicit confirmation for an echo→standard rotation. When the stored
+     * keyring has an `echo` block AND `newSecret` is a plain string, the
+     * rotation is a security-posture downgrade — and that shape is decided
+     * purely by argument shape, so it must be opted into explicitly. Without
+     * this flag such a rotation throws `ValidationError` BEFORE any write
+     * (and before deriving the new KEK). Upgrades (string→parts) and
+     * same-mode rotations (string→string, parts→parts) never require it.
+     */
+    readonly allowModeDowngrade?: boolean;
     /**
      * Map of slot id → re-enrolment ceremony. Slots whose id appears
      * here are PRESERVED across rotation (the ceremony re-derives the
@@ -99,7 +157,13 @@ export interface RotateSecretInput {
  * the rewrapped slots atomically with the rotation. Slots whose id
  * isn't in the map are still dropped.
  *
+ * Either secret may be a string or 3-part {@link EchoSecretParts}; the two
+ * shapes are independent, so a rotation doubles as the standard↔echo
+ * upgrade/downgrade ceremony (spec #940).
+ *
  * @throws `InvalidKeyError` if `oldSecret` does not unwrap the keyring.
+ * @throws `EchoCeremonyRequiredError` if `oldSecret` is a string but the
+ *         keyring is an echo keyring.
  * @throws `WeakSecretError` if `newSecret` fails the strength rule.
  * @throws `ValidationError` if a ceremony's result mismatches the
  *         slot's id or method (anti-slot-swap guard).
@@ -130,9 +194,38 @@ export type RecoveryProof = {
     };
 };
 export interface RecoverSecretInput {
-    readonly newSecret: string;
+    /**
+     * The secret to recover TO. As in {@link RotateSecretInput}, the shape
+     * decides the recovered keyring's mode: 3-part {@link EchoSecretParts}
+     * enroll a fresh (always PORTABLE) `echo` block, a string leaves the
+     * keyring standard and removes any block the old one carried.
+     *
+     * Recovery deliberately has no `echoOptions` counterpart — a device seal
+     * would bind the reveal blob to the device running the recovery, which is
+     * not necessarily the device the user will unlock from. Seal it afterwards
+     * with an explicit `rotateSecret`.
+     *
+     * A string `newSecret` on a previously-echo keyring performs the same
+     * echo→standard downgrade as `rotateSecret`, but WITHOUT an
+     * `allowModeDowngrade` gate — recovery is already a proof-gated reset
+     * ceremony (a valid recovery code/shares), so the shape-alone check
+     * `rotateSecret` needs is redundant here by design.
+     */
+    readonly newSecret: string | EchoSecretParts;
     readonly recoveryProof: RecoveryProof;
+    /**
+     * Strength-policy knobs applied when `newSecret` is a STRING. Ignored
+     * for 3-part {@link EchoSecretParts} — see `echoSecretPolicy` for the
+     * parts-path counterpart.
+     */
     readonly secretPolicy?: SecretPolicy;
+    /**
+     * Strength-policy knobs applied when `newSecret` is 3-part
+     * {@link EchoSecretParts} (prompt / combined floors). Ignored for a
+     * string `newSecret` — see `secretPolicy` for the string-path
+     * counterpart.
+     */
+    readonly echoSecretPolicy?: EchoSecretPolicy;
     readonly allowWeakSecret?: boolean;
     /**
      * After a successful paper-recovery, replace ALL remaining recovery
@@ -273,3 +366,4 @@ export type RecoveryEnrollmentInput = {
  * stored set).
  */
 export declare function recoverSecret(provider: ShamirRecoveryProvider | undefined, store: NoydbStore, vault: string, userId: string, input: RecoverSecretInput): Promise<UnlockedKeyring>;
+export {};

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

@@ -0,0 +1,9 @@
+import type { NoydbStore } from '../kernel/types.js';
+/**
+ * Return the stable opaque bundle handle for the given vault adapter,
+ * generating and persisting a fresh ULID on first call.
+ *
+ * See {@link import('../kernel/vault.js').Vault.getBundleHandle} for
+ * the full rationale and storage-path documentation.
+ */
+export declare function buildBundleHandle(adapter: NoydbStore, name: string): Promise<string>;

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

@@ -32,7 +32,9 @@
  * call can also feed verification tools, format inspectors, or
  * archive utilities that don't care about decryption.
  */
-import { type NoydbPodHeader } from './format.js';
+import { type NoydbPodHeader, type UnlockMethod } from './format.js';
+import type { Redirect } from './redirect.js';
+import type { DocSigner } from '../with-audit/attestation/signer.js';
 import type { Vault } from '../kernel/vault.js';
 import type { BundleRecipient } from '../with-party/team/keyring.js';
 import type { Cover } from '../with-party/directory/cover/types.js';
@@ -230,6 +232,39 @@ export interface WritePodOptions {
         readonly provider: SealingKeyProvider;
         readonly perUser: Record<string, string>;
     };
+    /**
+     * Pod-header signing control (#943).
+     *
+     *   - omitted (default) — sign the header iff the source vault has a
+     *     persisted document signer (`vault._loadPodSigner()` returns
+     *     non-null). A vault that never minted a signer produces an
+     *     unsigned `formatVersion: 1` header, exactly as before.
+     *   - `false` — never sign, even if a signer is persisted.
+     *   - an explicit {@link DocSigner} — sign with the supplied keypair
+     *     without touching the vault's persisted signer (test / advanced
+     *     injection). Does not mint or persist anything.
+     *
+     * Signing NEVER mints a signer as a side effect of export: an absent
+     * signer means an unsigned pod, not an on-the-fly key generation.
+     */
+    readonly sign?: false | DocSigner;
+    /**
+     * Header L2 fields (#942) — pre-auth dispatch metadata written verbatim
+     * into the pod header. See `NoydbPodHeader` for the disclosure rationale
+     * of each. All optional; absence produces a legacy-shaped header exactly
+     * as before.
+     */
+    readonly engineRange?: string;
+    readonly unlockMethods?: readonly UnlockMethod[];
+    readonly hasApp?: boolean;
+    readonly species?: 'full' | 'connection' | 'snapshot' | 'redirect' | 'group';
+    readonly pointerMode?: 'public' | 'private';
+    /**
+     * Signed "this moved, go there" pointer (#944), written verbatim into
+     * the plaintext header. Pass an already-signed {@link Redirect}
+     * (mint one via `signRedirect`) — `writePod` does not sign it for you.
+     */
+    readonly redirect?: Redirect;
 }
 /** @deprecated Use `WritePodOptions`. */
 export type WriteNoydbBundleOptions = WritePodOptions;
@@ -353,7 +388,14 @@ export declare function assembleBundleContainer(opts: {
     bodyJsonStr: string;
     compression: WritePodOptions['compression'];
     /** Header fields beyond the always-present four. */
-    headerExtras?: Partial<Pick<NoydbPodHeader, 'publicEnvelope' | 'autoUnlock' | 'bundleKind' | 'transferSeal'>>;
+    headerExtras?: Partial<Pick<NoydbPodHeader, 'publicEnvelope' | 'autoUnlock' | 'bundleKind' | 'transferSeal' | 'engineRange' | 'unlockMethods' | 'hasApp' | 'species' | 'pointerMode' | 'redirect'>>;
+    /**
+     * When present, the assembled header is signed (#943): the header is
+     * bumped to `formatVersion: 2` and carries the sig/keyId/sigAlg tuple.
+     * Absent → an unsigned `formatVersion: 1` header (partitions, and pods
+     * from vaults without a signer, stay unsigned).
+     */
+    signer?: DocSigner;
 }): Promise<Uint8Array>;
 export declare function writePod(vault: Vault, opts?: WritePodOptions): Promise<Uint8Array>;
 /** @deprecated Use `writePod`. */
@@ -375,6 +417,50 @@ export declare const writeNoydbBundle: typeof writePod;
 export declare function readPodHeader(bytes: Uint8Array): NoydbPodHeader;
 /** @deprecated Use `readPodHeader`. */
 export declare const readNoydbBundleHeader: typeof readPodHeader;
+/**
+ * Outcome of {@link verifyPodHeader}.
+ *
+ *   - `verified`  — the header carried a sig-tuple, its `keyId` is in
+ *     `trustedKeys`, and the signature checks out over the canonical
+ *     header bytes.
+ *   - `unsigned`  — the header carried no signature (a legacy v1 pod, or a
+ *     v2 pod written with `{ sign: false }`). Not an error; just unauthenticated.
+ *   - `untrusted` — the header is signed but its `keyId` is not one the
+ *     caller trusts. The signature was NOT checked.
+ *   - `tampered`  — the header is signed by a trusted key but the signature
+ *     does not verify: the signed bytes were altered, or the mapped public
+ *     key is not the one that actually signed.
+ */
+export interface PodVerifyResult {
+    readonly status: 'verified' | 'unsigned' | 'untrusted' | 'tampered';
+    /** The header's `keyId`, present whenever the header carried a sig-tuple. */
+    readonly keyId?: string;
+}
+/**
+ * Authenticate a pod header (#943) — a pure, dependency-free, WebCrypto-only
+ * verifier. Given only the raw pod bytes and a `trustedKeys` map
+ * (`keyId → publicKeyB64` the caller already trusts), it reports whether the
+ * header was signed by a trusted document signer.
+ *
+ * Pairs with the signing half in `assembleBundleContainer`/`writePod`: the
+ * signed payload is the final wire header with `sig` removed, so verification
+ * reconstructs it by stripping EXACTLY the `sig` field — `keyId`, `sigAlg`,
+ * and every other header field stay in the verified payload.
+ *
+ * No store, enclave, or vault dependency — reachable from a static page with
+ * only the pod bytes, the trusted-key map, and `globalThis.crypto`.
+ *
+ * SECURITY — authenticity is not integrity. A `verified` result proves the
+ * header (which includes the *claimed* `bodySha256`) is signed by a trusted
+ * key; it does NOT prove the body matches that hash. To trust the pod's
+ * BODY you MUST also confirm the body hashes to `header.bodySha256` — call
+ * `readPod`, which throws `BundleIntegrityError` on mismatch. A `verified`
+ * header paired with a swapped body is caught only by that integrity check.
+ * This function stays body-free by design so a static page can authenticate a
+ * header without decompressing the body; composing the two checks is the
+ * caller's responsibility. See `docs/subsystems/pod-signature.md`.
+ */
+export declare function verifyPodHeader(bytes: Uint8Array, trustedKeys: Readonly<Record<string, string>>): Promise<PodVerifyResult>;
 /**
  * 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
@@ -391,6 +477,18 @@ export declare const readNoydbBundleHeader: typeof readPodHeader;
 export declare function readPodCover(bytes: Uint8Array, opts?: {
     readonly locale?: string;
 }): Cover | undefined;
+/**
+ * Read just the bundle's Redirect record (#944) — without verifying the
+ * body or even parsing the dump JSON. Pass the raw bundle bytes; receive
+ * the header's `redirect` field or `undefined` if the bundle was written
+ * without one.
+ *
+ * The record is returned UNVERIFIED: `validateBundleHeader` only checks
+ * its shape at parse time (a parser has no `trustedKeys`). Callers that
+ * intend to follow the redirect MUST separately call `verifyRedirect`
+ * (`redirect.js`) before trusting `target`.
+ */
+export declare function readPodRedirect(bytes: Uint8Array): Redirect | undefined;
 /**
  * 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

@@ -46,12 +46,15 @@
  * bundle and verify its integrity — nothing about the contents.
  */
 import type { Cover } from '../with-party/directory/cover/types.js';
+import type { Redirect } from './redirect.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. */
 export declare const NOYDB_BUNDLE_PREFIX_BYTES = 10;
-/** Current bundle format version. Bumped on layout changes. */
+/** Current bundle format version. Bumped on layout changes. Default for unsigned pods. */
 export declare const NOYDB_BUNDLE_FORMAT_VERSION = 1;
+/** Format version for pods carrying a header signature (`sig`/`keyId`/`sigAlg`). */
+export declare const NOYDB_BUNDLE_FORMAT_VERSION_SIGNED = 2;
 /**
  * Bitfield interpretation of the flags byte.
  *
@@ -157,7 +160,95 @@ export interface NoydbPodHeader {
         readonly alg: 'aes-256-gcm-pre-shared';
         readonly sealId: string;
     };
+    /**
+     * Non-secret 16-hex-char fingerprint identifying the signing key
+     * used for `sig`. A hash prefix, not the key itself — discloses no
+     * crypto config, safe under minimum-disclosure. Present iff `sig`
+     * and `sigAlg` are also present (all-or-nothing 3-tuple), and only
+     * on `formatVersion === 2` headers.
+     */
+    readonly keyId?: string;
+    /**
+     * Signature authenticating the rest of the header (base64url,
+     * no padding). Verifies the header wasn't tampered with in
+     * transit/storage — see `with-pod/signature.ts`. Part of the
+     * sig/keyId/sigAlg 3-tuple.
+     */
+    readonly sig?: string;
+    /**
+     * Signature algorithm for `sig`. Named `sigAlg` (not `alg`) to
+     * avoid confusion with `transferSeal.alg`. Part of the
+     * sig/keyId/sigAlg 3-tuple.
+     */
+    readonly sigAlg?: 'ed25519';
+    /**
+     * Engine version range that wrote (and can read) this pod, e.g.
+     * `'^0.5.0'`. Discloses only a semver range — no timestamps, no
+     * identities — so a version-skew triage step (open a decade-old
+     * pod → route to a version-matched read-only player instead of a
+     * hard failure) or a landing page can branch before any library
+     * code runs. Safe under minimum-disclosure: a range says nothing
+     * about who wrote the pod or when.
+     */
+    readonly engineRange?: string;
+    /**
+     * Declared unlock method(s), e.g. `['password', 'webauthn']`. Lets
+     * a landing/player present the right unlock UI pre-library, and is
+     * ALL a shared connection pod may disclose about its bootstrap
+     * (auth method + endpoint class). Safe under minimum-disclosure: it
+     * names a method family, not a credential, key, or identity.
+     *
+     * The member set mirrors the `@noy-db/on-*` package family
+     * (`on-password`, `on-webauthn`, `on-oidc`, `on-totp`,
+     * `on-email-otp`, `on-magic-link`, `on-pin`, `on-recovery`,
+     * `on-shamir`) — the top-level "which on-* package to load" method
+     * name, not the finer-grained `FactorKind` used by policy gates
+     * (which splits WebAuthn into `webauthn-roaming` /
+     * `webauthn-platform` for factor-proof freshness). `on-threat` is
+     * excluded — it's a lockout/duress helper, not an unlock method a
+     * landing page would present.
+     */
+    readonly unlockMethods?: readonly UnlockMethod[];
+    /**
+     * App-manifest presence flag. Lets a landing fork between
+     * "orphan pod → read-only browse" and "linked app → launch flow"
+     * without reading the body. Safe under minimum-disclosure: a
+     * boolean, not the app's identity or contents.
+     */
+    readonly hasApp?: boolean;
+    /**
+     * Artifact species hint for dispatcher branching, cloud tooling,
+     * and the share-flow guard that warns when a data-bearing pod is
+     * shared where a pointer was intended. An "orphan" pod is derived
+     * (`species: 'full'` + `hasApp: false`), not a separate species.
+     * Safe under minimum-disclosure: a coarse artifact-shape label, not
+     * contents or identity.
+     */
+    readonly species?: 'full' | 'connection' | 'snapshot' | 'redirect' | 'group';
+    /**
+     * Whether the app pointer (if any) is disclosed pre-auth. Default
+     * is `'private'` by product decision (recorded in #942) — absence
+     * means private by convention; this field is never auto-injected,
+     * only an author's explicit opt-in writes `'public'`. Safe under
+     * minimum-disclosure: a disclosure-policy flag, not the pointer
+     * itself.
+     */
+    readonly pointerMode?: 'public' | 'private';
+    /**
+     * Signed "this moved, go there" pointer (#944). Carried in the
+     * PLAINTEXT header (not the encrypted body) so a dispatcher can follow
+     * it pre-auth — no secret, no decompression. Structurally validated
+     * here (shape only); the record's OWN signature is a separate
+     * verification step (`verifyRedirect`) since a parser has no
+     * `trustedKeys`. `readPodRedirect` returns this field UNVERIFIED.
+     */
+    readonly redirect?: Redirect;
 }
+/**
+ * Declared unlock method names — mirrors the `@noy-db/on-*` package
+ * family (see `unlockMethods` doc comment on `NoydbPodHeader`).
+ */
+export type UnlockMethod = 'password' | 'webauthn' | 'oidc' | 'totp' | 'email-otp' | 'magic-link' | 'pin' | 'recovery' | 'shamir';
 /** @deprecated Use `NoydbPodHeader`. */
 export type NoydbBundleHeader = NoydbPodHeader;
 /**