safebyok 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# safebyok
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bring Your Own Key (BYOK) Browser Vault using E2EE (End-to-end Encryption) and pluggable remote storage
+
+`safebyok` gives users a secure "Bring Your Own Key" vault. Secrets are available on their own device and nowhere else.
+
+* Secrets are always stored in encrypted form, using keys that never leave the end-user's device
+* Secrets synchronize across multiple devices using a passphrase the user controls
+* The user may change their passphrase without re-entering their information
+* Accessing a vault is prohibitively difficult -- even given the application's database, code and environment.
+
+It is react-friendly (`safebyok-react`) and database agnostic: storage adapters implement a small
+abstract seam, IndexedDB adapters ship in `safebyok/idb`, and a Convex adapter is planned.
+`whiteboard/20261013-relic/proposed-README.md` drafts the full README for when the surface
+settles.

package/dist/device-db-D3SBnJdR.d.cts

@@ -0,0 +1,326 @@
+import * as Z from "zod";
+//#region src/types.d.ts
+/**
+ * The JSON a whisper is made of. `null` is legal here -- inside an array or object -- because
+ * real JSON payloads carry it; see {@link Whisper} for why a whisper can't be null as a whole.
+ */
+type WhisperJson = string | number | boolean | null | WhisperJson[] | {
+  [ckey: string]: WhisperJson;
+};
+/**
+ * The secret kept in a lockbox: a JSON value -- a string, number, boolean, array or plain object.
+ * Two shapes are refused rather than silently mangled:
+ *  * `undefined`, anywhere in the value: JSON cannot carry it.
+ *  * a bare `null` as the whole whisper: nobody's secret is "nothing here", and emptying a
+ *    lockbox is `erase`'s job. (`null` inside a structure is fine: {@link WhisperJson}.)
+ *
+ * @example 'sk-ant-api03-...'
+ * @example { apiKey: 'sk-ant-...', orgId: null }
+ */
+type Whisper = Exclude<WhisperJson, null>;
+/**
+ * Validator for a {@link Whisper}: accepts exactly what JSON can carry, refuses what JSON would
+ * mangle (undefined, functions, class instances such as Date or Map), and refuses a bare null.
+ *
+ * @example Whisper.parse('sk-ant-...')                  // a string passes through
+ * @example Whisper.safeParse(new Date()).success        // false: JSON would flatten it to {}
+ * @example Whisper.safeParse(undefined).success         // false: undefined cannot be stored
+ * @example Whisper.safeParse(null).success              // false: emptying a lockbox is erase's job
+ * @example Whisper.safeParse({ orgId: null }).success   // true: null inside a structure is JSON
+ */
+declare const Whisper: Z.ZodType<Whisper>;
+/**
+ * A freely chosen identifier (STYLE.md tag glossary): lowercase words of letters and digits
+ * joined by single underscores, starting with a letter, two to forty characters. Shared by every
+ * label in the package: `applabel`, `vaultlabel`, `boxlabel`, `userlabel`.
+ *
+ * @example Label.parse('anthropic_api_key')
+ * @example Label.safeParse('ANTHROPIC_API_KEY').success  // false: lowercase only
+ * @example Label.safeParse('_nope').success              // false
+ */
+declare const Label: Z.ZodString;
+/**
+ * What names one vault: the host application's label, the authenticated user, and the vault's own
+ * label. Two users may each have a vault labelled `main` without collision; so may two apps
+ * sharing a backend.
+ */
+declare const VaultScope: Z.ZodObject<{
+  applabel: Z.ZodString;
+  user_id: Z.ZodString;
+  vaultlabel: Z.ZodString;
+}, Z.z.core.$strip>;
+type VaultScope = Z.infer<typeof VaultScope>;
+/**
+ * One lockbox as the storage layer holds it: the whisper ciphered under its own lockboxKey, that
+ * lockboxKey wrapped under the vaultKey, and the public shell -- boxlabel, note, timestamps --
+ * a locked vault may show. Nothing in this record opens without the vaultKey.
+ *
+ * `revision_id` is minted fresh on every write and bound into both encryptions, so ciphertext
+ * moved between revisions (or boxes, or vaults) refuses to open.
+ *
+ * Stored fields are underbar_case: this record is written to the storage layer as-is, and it is
+ * plain JSON -- any backend that can hold text can hold it.
+ */
+declare const Lockbox: Z.ZodObject<{
+  format: Z.ZodLiteral<"safebyok-lockbox-v1">;
+  boxlabel: Z.ZodString;
+  revision_id: Z.ZodString;
+  lockbox_key_wrapped: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  whisper_ciphered: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  note: Z.ZodOptional<Z.ZodString>;
+  created_at: Z.ZodString;
+  updated_at: Z.ZodString;
+}, Z.z.core.$strip>;
+type Lockbox = Z.infer<typeof Lockbox>;
+/**
+ * The public face of a lockbox: everything but its two encrypted fields. This is what `list()`
+ * returns and what a locked vault may show.
+ */
+declare const LockboxSummary: Z.ZodObject<{
+  boxlabel: Z.ZodString;
+  revision_id: Z.ZodString;
+  note: Z.ZodOptional<Z.ZodString>;
+  created_at: Z.ZodString;
+  updated_at: Z.ZodString;
+}, Z.z.core.$strip>;
+type LockboxSummary = Z.infer<typeof LockboxSummary>;
+/**
+ * The per-vault record the storage layer holds so any device can unlock the vault: the
+ * passphraseSalt, the keyDeriverLabel saying how the passphraseKey is made, and the vaultKey
+ * wrapped under that passphraseKey. All of it is safe in the open; none of it opens without
+ * the passphrase.
+ *
+ * `passphrase_epoch` goes up by one on every passphrase change, so other devices and remembered
+ * unlocks know to ask again.
+ */
+declare const VaultBundle: Z.ZodObject<{
+  format: Z.ZodLiteral<"safebyok-vault-v1">;
+  applabel: Z.ZodString;
+  user_id: Z.ZodString;
+  vaultlabel: Z.ZodString;
+  vault_id: Z.ZodString;
+  passphrase_epoch: Z.ZodNumber;
+  key_deriver_label: Z.ZodString;
+  passphrase_salt_b64: Z.ZodString;
+  vault_key_passphrase_wrapped: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  created_at: Z.ZodString;
+  updated_at: Z.ZodString;
+}, Z.z.core.$strip>;
+type VaultBundle = Z.infer<typeof VaultBundle>;
+/**
+ * The device-local record of a remembered unlock: this browser's localUnlockKey (a
+ * non-extractable handle -- it cannot leave the device even through the code that made it) and
+ * the vaultKey wrapped under it. Held only by structured-clone storage (IndexedDB) or memory;
+ * it has no JSON form, and nothing in it ever goes to the backend.
+ */
+declare const DeviceUnlock: Z.ZodObject<{
+  format: Z.ZodLiteral<"safebyok-unlock-v1">;
+  applabel: Z.ZodString;
+  user_id: Z.ZodString;
+  vaultlabel: Z.ZodString;
+  vault_id: Z.ZodString;
+  passphrase_epoch: Z.ZodNumber;
+  local_unlock_key: Z.ZodCustom<CryptoKey, CryptoKey>;
+  vault_key_local_wrapped: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  expires_at: Z.ZodNumber;
+}, Z.z.core.$strip>;
+type DeviceUnlock = Z.infer<typeof DeviceUnlock>;
+/** How long an entered passphrase is remembered on the device, unless the caller says otherwise. */
+declare const SevenDaysMs: number;
+/**
+ * The largest whisper a vault stores unless the caller says otherwise, in bytes of its JSON:
+ * several times the beefiest credential (an RSA-8192 private key as PEM is about 6.4 KB), and
+ * well inside what every storage backend can hold. A larger whisper is usually a sign that the
+ * wrong value is being stored.
+ */
+declare const MaxWhisperBytes = 40444;
+/** Injected time source, so expiry is testable; defaults to the wall clock. */
+type Clock = {
+  now(): number;
+};
+/** The wall clock: the default `Clock`. */
+declare const wallClock: Clock;
+//#endregion
+//#region src/string-store.d.ts
+/**
+ * The smallest storage the stub adapters need: strings by string ckey, with change notification
+ * so the vault and the demo's inspector can watch it. The browser demo backs one with
+ * localStorage; the tests back one with a Map.
+ */
+type StringStore = {
+  /** The stored text under `ckey`, or null when there is none. */
+  read(ckey: string): string | null;
+  write(ckey: string, text: string): void;
+  erase(ckey: string): void;
+  /** Every ckey currently stored, in no particular order. */
+  ckeys(): string[];
+  /** Calls `listener` after any write or erase; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+};
+/**
+ * In-memory StringStore over a Map: what the tests use, and a fallback anywhere localStorage
+ * is missing.
+ *
+ * @example
+ *   const store = memoryStore()
+ *   store.write('greeting', 'hi'); store.read('greeting')  // 'hi'
+ */
+declare const memoryStore: () => StringStore;
+/**
+ * StringStore over a DOM Storage object (localStorage), confined to one prefix: each store sees
+ * only its own entries, so the demo can keep a pretend-remote database and a device cache in the
+ * same localStorage while showing them as the distinct places they stand in for.
+ *
+ * Change notification covers this tab's own writes (DOM `storage` events only fire in *other*
+ * tabs, which the demo does not chase).
+ *
+ * @param webStorage - The Storage to write through, usually `window.localStorage`.
+ * @param prefix - Namespace for this store's entries, e.g. 'safebyok-demo:db:'.
+ *
+ * @example
+ *   const dbStore = domStore(localStorage, 'safebyok-demo:db:')
+ *   dbStore.write('vault:acme:u1:main', text)   // lands at 'safebyok-demo:db:vault:acme:u1:main'
+ */
+declare const domStore: (webStorage: Storage, prefix: string) => StringStore;
+//#endregion
+//#region src/vault-db.d.ts
+/**
+ * Remote storage for vault records, as the host application plugs it in: extend this class and
+ * implement the seven `fetch`/`save`/`trash` primitives against your backend. That is the whole
+ * job -- you are a shelf, not a safe:
+ *
+ *  * **Store what you are handed, return what you stored.** Every record is plain JSON (binary
+ *    fields are base64url text), so any backend that can hold JSON can hold a vault, as-is.
+ *  * **Never look inside.** Every secret field arrives encrypted; nothing you hold can open a
+ *    vault, and nothing safebyok does ever needs you to understand a record.
+ *  * **Enforce who may reach which rows.** Your backend should let a signed-in user reach only
+ *    their own records: safebyok's encryption protects the contents, your authorization decides who
+ *    may fetch or overwrite them at all.
+ *  * **Don't repair.** Return a record exactly as stored, or null when there is none. safebyok
+ *    validates everything it reads back; a damaged record is safebyok's to refuse, never yours to fix
+ *    or quietly drop.
+ *
+ * The verbs the vault actually calls -- `readBundle`, `listBoxes`, `eraseVault` and the rest --
+ * are built for you on top of your primitives, validation included. Each compound verb documents
+ * the default composition; a backend that can do better (a transactional delete, a projected
+ * list, a push subscription) overrides that one method and leaves the rest.
+ */
+declare abstract class VaultDB {
+  /**
+   * The most this backend holds in one record, in bytes: a plain fact about the backend, or
+   * `Infinity` when it sets no per-record limit. A vault refuses to open with a `maxWhisperBytes`
+   * over half of it, leaving room for encoding and the record's other fields.
+   */
+  abstract readonly maxRecordBytes: number;
+  /** The stored bundle record for `scope`, exactly as saved, or null when there is none. */
+  protected abstract fetchBundle(scope: VaultScope): Promise<unknown>;
+  /** Store `bundle`, replacing any bundle already under its scope. */
+  protected abstract saveBundle(bundle: VaultBundle): Promise<void>;
+  /** Remove the bundle record for `scope`; succeed quietly when there is none. */
+  protected abstract trashBundle(scope: VaultScope): Promise<void>;
+  /** The stored lockbox record under `boxlabel`, exactly as saved, or null when there is none. */
+  protected abstract fetchBox(scope: VaultScope, boxlabel: string): Promise<unknown>;
+  /** Store `lockbox`, replacing any lockbox already under its boxlabel. */
+  protected abstract saveBox(scope: VaultScope, lockbox: Lockbox): Promise<void>;
+  /** Remove the lockbox record under `boxlabel`; succeed quietly when there is none. */
+  protected abstract trashBox(scope: VaultScope, boxlabel: string): Promise<void>;
+  /** Every stored lockbox record in `scope`, in any order. */
+  protected abstract fetchBoxes(scope: VaultScope): Promise<unknown[]>;
+  /** The vault's bundle, validated, or null when the vault has never been created. */
+  readBundle(scope: VaultScope): Promise<VaultBundle | null>;
+  /** Store `bundle`, replacing whatever bundle its scope held. */
+  writeBundle(bundle: VaultBundle): Promise<void>;
+  /**
+   * Store `bundle` only if its scope holds none, and return whichever bundle ends up there: the
+   * given one, or the one another device got in first with.
+   *
+   * Default composition: a fetch, then a save -- two devices creating at the same instant can
+   * still race between those steps. A backend with an atomic create should override this with
+   * one, and resolve the race for real.
+   */
+  createBundle(bundle: VaultBundle): Promise<VaultBundle>;
+  /** One lockbox record, validated, or null when there is none under that label. */
+  readBox(scope: VaultScope, boxlabel: string): Promise<Lockbox | null>;
+  /** Store `lockbox`, replacing whatever its boxlabel held. */
+  writeBox(scope: VaultScope, lockbox: Lockbox): Promise<void>;
+  /** Remove the lockbox under `boxlabel`. */
+  eraseBox(scope: VaultScope, boxlabel: string): Promise<void>;
+  /**
+   * Public faces of every lockbox in the vault -- ciphered fields stripped, sorted by boxlabel --
+   * valid while locked.
+   *
+   * Default composition: fetch every full record and strip it here. A backend that can project
+   * away the ciphered fields server-side should override this and skip hauling them.
+   */
+  listBoxes(scope: VaultScope): Promise<LockboxSummary[]>;
+  /**
+   * Remove the bundle and every lockbox: the backend's part of deleting a vault.
+   *
+   * Default composition: trash each lockbox, then the bundle -- an interruption can strand some
+   * rows, though never usable ones. A backend with a transaction or batch delete should override
+   * this with one.
+   */
+  eraseVault(scope: VaultScope): Promise<void>;
+  /**
+   * Calls `onChange` after any write touching `scope`, from this device or another; returns the
+   * unsubscribe. The default never calls: safebyok refreshes after its own writes regardless, so all
+   * a silent backend loses is news of *other* devices' writes. A backend with live queries or
+   * push (Convex, a websocket) should override this and ring the bell.
+   */
+  subscribe(_scope: VaultScope, _onChange: () => void): () => void;
+}
+/**
+ * VaultDB over a {@link StringStore}: rows as JSON text under scope-prefixed ckeys. The demo
+ * backs one with localStorage to stand in for a real backend; tests back one with a Map. Every
+ * secret field in what it stores is ciphertext, so the only thing pretend about it is reach --
+ * rows stay on this device instead of syncing through a shared database.
+ *
+ * @example
+ *   const vaultDB = localVaultDB(memoryStore())
+ *   await vaultDB.readBundle({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null
+ */
+declare const localVaultDB: (store: StringStore) => VaultDB;
+//#endregion
+//#region src/device-db.d.ts
+/**
+ * Device-local storage for remembered unlocks: what lets "enter your passphrase once, keep it for
+ * seven days" survive a page reload. A {@link DeviceUnlock} record holds this browser's
+ * localUnlockKey -- a non-extractable CryptoKey handle, which has no JSON form -- so an adapter
+ * must keep records by structured clone (IndexedDB: see `safebyok/idb`) or in memory; nothing here
+ * ever goes to the backend.
+ *
+ * An adapter may answer a damaged or unreadable record with null rather than an error: losing a
+ * remembered unlock only means asking for the passphrase again, and that is the safe failure.
+ */
+interface DeviceDB {
+  /** The remembered unlock for one vault, or null when there is none. Expiry is the vault's call. */
+  readUnlock(scope: VaultScope): Promise<DeviceUnlock | null>;
+  writeUnlock(unlock: DeviceUnlock): Promise<void>;
+  eraseUnlock(scope: VaultScope): Promise<void>;
+  /** Remove every remembered unlock on this device: the device's part of a full reset. */
+  eraseAll(): Promise<void>;
+}
+/**
+ * DeviceDB over a Map: what the tests use, and the fallback anywhere without IndexedDB. Remembered
+ * unlocks last exactly as long as the page -- which is to say, it remembers nothing, safely.
+ *
+ * @example
+ *   const deviceDB = memoryDeviceDB()
+ *   await deviceDB.readUnlock({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null
+ */
+declare const memoryDeviceDB: () => DeviceDB;
+//#endregion
+export { Whisper as _, StringStore as a, Clock as c, Lockbox as d, LockboxSummary as f, VaultScope as g, VaultBundle as h, localVaultDB as i, DeviceUnlock as l, SevenDaysMs as m, memoryDeviceDB as n, domStore as o, MaxWhisperBytes as p, VaultDB as r, memoryStore as s, DeviceDB as t, Label as u, WhisperJson as v, wallClock as y };
+//# sourceMappingURL=device-db-D3SBnJdR.d.cts.map