# Toshokann storage, security, and privacy Toshokann derivative applications use application-scoped DBOPFS, a small database abstraction over the browser's Origin Private File System (OPFS), for browser-local working records. This document defines the boundary of that choice. DBOPFS is a persistence mechanism. It is not, by itself, encryption, authentication, authorization, audit, backup, secure deletion, privacy governance, or compliance. The live GitHub Pages site at `https://thewizardnexus.github.io/Toshokann/` is documentation only. Its positive publication allowlist excludes `app.html`, the core runtime, DBOPFS, the local-document store, and the reference extension. Visiting the documentation site does not open or populate Toshokann storage. A derivative must package and run the application runtime before the behavior below applies. ## Storage model DBOPFS stores tables as directories and records as files in OPFS. Before it opens storage, the shared application-data scope resolves a canonical application identity. In a browser-only deployment, the page must declare that identity. In a supported native host, the host-bound identity is authoritative and a mismatch with the page declaration fails closed. The database opens this logical location beneath the OPFS root: ```text apps/// ``` This layout prevents accidental collisions among cooperating applications and lets clear operations stay within the selected application directory. It is not browser-enforced access control between same-origin applications. The relevant platform boundary is the browser storage key. The [WHATWG Storage Standard](https://storage.spec.whatwg.org/#storage-keys) defines how storage keys are obtained, and the [WHATWG File System Standard](https://fs.spec.whatwg.org/#origin-private-file-system) defines the origin-private file system exposed through the storage manager. Browsers may partition storage more narrowly, but a URL path does not create a distinct origin. Browser-hosted projects below `https://thewizardnexus.github.io/` therefore share the same origin; directories such as `apps/toshokann` and `apps/boss` are organizational within that browser boundary. A native host can provide stronger application separation by assigning each application a distinct WebView profile and binding the application identity outside page-controlled JavaScript. That stronger boundary belongs to the native deployment. It should not be inferred for an ordinary same-origin website. ## Security properties and non-properties ### What the foundation provides - A canonical application identity must be resolved before a data directory opens. - DBOPFS operations are directed beneath `apps/` for the active application. - Writes to the same record are serialized by the database layer. - Managed seed import is bounded by a configurable batch size, stable managed filenames, an incomplete marker, and prefix-scoped stale cleanup. - Library retrieval bounds ranked results plus per-document and total context characters and escapes its context envelope. - The inherited DBOPFS worker can perform supported OPFS reads and writes away from the main thread when the direct file-handle path is unavailable. ### What the foundation does not provide - Encryption at rest, field-level encryption, or encrypted backup exports. - User authentication, identity proofing, single sign-on, roles, permissions, RBAC, ABAC, need-to-know, or compartment enforcement. - Audit logging, tamper-evident events, nonrepudiation, chain of custody, legal hold, or records-management policy. - Malware detection, content safety, provenance, approval authority, classification authority, or release authority. - Guaranteed retention, disaster recovery, immutable storage, WORM behavior, certified deletion, or forensic erasure. - Automatic compliance with privacy, education, health, criminal-intelligence, public-records, export-control, preservation, or cybersecurity requirements. The BOSS-compatible library runtime does not independently enforce a catalog SHA-256 digest while hydrating Markdown. A derivative may add a hash- or signature-bound release layer, but even a digest match is only an integrity fact: the bytes equal a declared value. It does not prove who created or approved the content, that the declaration is authentic, that the content is current or harmless, or that a particular person may receive it. The worker path is a performance and compatibility mechanism. A worker executes within the application's web security environment and does not create a separate confidentiality boundary. ## Same-origin code and cross-site scripting OPFS is private from the user's ordinary file-system view, not private from code that is entitled to the same browser storage boundary. JavaScript executing with the same origin may be able to request the origin's OPFS root and traverse its directories. That includes code introduced by a cross-site scripting defect or a compromised same-origin script or dependency. The `apps/` convention helps honest applications avoid each other's records. It does not stop hostile same-origin code. Treat prevention of script injection and dependency compromise as protection for all browser-local records on that origin. A browser derivative should use a dedicated origin when applications must not trust one another. It should also use a restrictive Content Security Policy, avoid inline and dynamic code where practical, minimize third-party scripts, pin and review dependencies, render collection content as data rather than executable markup, and keep credentials and decryption keys out of the application bundle. ## Quota, persistence, clearing, and recovery OPFS is managed browser storage. Its capacity and lifetime are controlled by the user agent and device environment. [MDN's storage quota and eviction guidance](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria) describes implementation-specific quotas, best-effort eviction, persistent storage, and user clearing. [MDN's `StorageManager.persist()` reference](https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist) explains that a browser decides whether to grant a persistence request. Toshokann's inherited DBOPFS module may call `navigator.storage.persist()` and continues if the request is denied or unavailable. A grant can reduce pressure-based eviction in supporting browsers, but it is not a durability guarantee. It does not prevent a user from clearing site data, deleting a browser or WebView profile, uninstalling the host, losing the device, or suffering storage corruption. Each derivative must decide whether its records are disposable working copies or holdings that require recovery. If recovery matters, define and test an independent backup, restore, retention, migration, and incident-response process. Do not call OPFS itself a backup. ## Export and restore If a derivative retains and exposes the inherited `downloadCompressedPNG()` API, DBOPFS serializes table contents to JSON, compresses those bytes, and encodes the compressed payload into PNG pixels. The companion restore API extracts and decompresses the JSON before writing records back to OPFS. The `.png` filename and compressed representation do not provide encryption, authentication, access control, or secrecy. Treat the file as plaintext-equivalent data: - Store and transmit it only through channels approved for the underlying records. - Apply application-layer encryption when confidentiality is required, with keys managed separately from both the application bundle and backup. - Authenticate the backup and validate its schema, size, ownership, and intended application scope before restoring it. - Warn users that matching keys can be overwritten and preserve recovery evidence when policy requires it. - Do not use the export as proof of archival authenticity or as a sole disaster-recovery copy. ## Hardening a derivative Security belongs to the deployed system, not to one browser API. A derivative handling anything beyond low-sensitivity working text should document its threat model and add controls appropriate to the collection: 1. **Isolation:** use a dedicated web origin or a separately provisioned native WebView profile when another same-origin application must not reach the records. 2. **Code control:** enforce a restrictive CSP; review, minimize, and pin scripts and dependencies; prevent executable collection content; and test XSS defenses. 3. **Device protection:** require supported, patched devices; full-device encryption; session locking; endpoint protection; and an approved browser or native-host configuration. 4. **Application encryption:** encrypt sensitive records before DBOPFS writes them when the threat model requires it. Store and rotate keys through a separately protected mechanism; deletion of ciphertext is not secure deletion if keys or copies remain. 5. **Identity and authorization:** implement authentication, user lifecycle, least privilege, role or attribute policy, session controls, and administrative recovery outside the neutral storage layer. 6. **Audit and governance:** add logs appropriate to the risk, protect those logs, define approvals and release authority, and establish privacy, retention, legal-hold, deletion, and incident-response procedures. 7. **Backup and continuity:** maintain approved encrypted backups, test restore, document recovery objectives, and preserve required independent copies. 8. **Verification:** test the complete deployed boundary, including origin isolation, native profile binding, CSP, permissions, backup exposure, clearing behavior, and failure paths. A component-level DBOPFS test is not a system authorization. ## Protected and regulated use Toshokann can support a Library or Archive for material that an institution is already authorized to place within its deployed boundary. The base foundation is not, by itself, an approved environment for classified information, controlled unclassified information (CUI), criminal-intelligence records, protected student or health information, regulated evidence, credentials, secrets, export-controlled data, or other controlled holdings. For fusion centers and public-safety partnerships, the neutral foundation does not supply identity proofing, need-to-know, dissemination controls, auditing, source protection, classified or CUI handling, secure messaging, or criminal-intelligence compliance. For ISACs, ISAOs, and sector communities, it does not supply member authentication, TLP enforcement, secure exchange, STIX/TAXII, case management, confidentiality governance, or regulatory compliance. Those boundaries remain exactly as described in the use-case documentation. An organization considering protected use should obtain the approvals required for its environment and verify the complete derivative against its applicable technical, legal, contractual, records, privacy, and operational requirements. A use-case label, local storage, native wrapper, hash, application directory, or Toshokann license does not itself create that authorization. ## Platform references - [WHATWG Storage Standard: storage keys](https://storage.spec.whatwg.org/#storage-keys) - [WHATWG File System Standard: origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system) - [MDN: Origin private file system](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) - [MDN: Storage quotas and eviction criteria](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria) - [MDN: `StorageManager.persist()`](https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist) These platform references describe browser primitives. They do not certify Toshokann or a derivative for any security or compliance regime.