ulda-auth 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.1
+
+- Fix the release dry-run for versions already present in npm, with regression tests for dry-run safety and archive integrity.
+- Clarify GitHub Actions rehearsals, trusted publisher configuration and maintainer approval in the publishing guide.
+- SDK runtime, public API, wire protocol, cryptographic profile and dependencies are unchanged from 1.0.0.
+
+## 1.0.0
+
+- Initial public SDK package: encrypted master/content lifecycle over ULDA and Socket.IO.
+- Per-resource chains, binary transport, subscriptions, X/S queues and explicit conflict handling.
+- Bounded reconnect with verified reads; no automatic replay of uncertain writes.
+- Fail-closed incoming validation, explicit content recovery and private secret lifecycle.
+- ESM and standalone browser exports, TypeScript declarations and pinned core dependency.
+- Security regressions, safe test output, package checks and publication dry-run.

package/LICENSE.md

@@ -0,0 +1,380 @@
+# ULDA Library Community Source License 1.0
+
+Version 1.0 — 6 October 2026
+
+Copyright in the respective contributions © 2026 Mark Shaposhnik and
+Vitalii Radko.
+
+ULDA protocol and library concept: Mark Shaposhnik.
+
+Library implementation contributions and improvements: Vitalii Radko.
+
+## 1. Scope and acceptance
+
+“Licensors” means Mark Shaposhnik and Vitalii Radko, each solely with respect
+to the rights that person owns or is authorized to license in the Covered
+Materials.
+
+“Covered Materials” means the source code and generated bundles of
+`ulda-auth`, together with the ULDA Library Manifest, protocol documentation, test
+vectors, examples, and other materials expressly identified as part of an
+official `ulda-auth` release distributed with this License.
+
+Third-party materials and separately licensed files are excluded.
+
+This License text is not a Covered Material and may be copied and distributed
+verbatim.
+
+This License applies only to ULDA Library (the SDK), currently packaged as
+`ulda-auth` (formerly `@ulda/library-prototype`), and to releases expressly identified as covered by
+this License. A package rename alone does not extend its scope to other
+products. The internal project name `ulda-library` refers to this SDK.
+
+`ulda-core`, Socket.IO, and all other dependencies retain their own licenses,
+including when included in an SDK bundle or vendor archive. This License does
+not replace their terms or grant additional rights in them. ULDA servers,
+SaaS or API services, container images, Enterprise products, and other
+separately distributed products require their own terms.
+
+By exercising any permission granted under this License, You accept its terms.
+If You do not accept them, You may not exercise those permissions.
+
+Nothing in this License restricts an act that applicable law permits and does
+not allow the Licensors to prohibit by contract.
+
+This is a source-available license. It is not an OSI-approved open-source
+license.
+
+## 2. Definitions
+
+“You” means the individual or Organization exercising permissions under this
+License.
+
+“Organization” means a corporation, company, partnership, sole proprietorship,
+association, foundation, non-profit organization, educational institution,
+public body, government body, or other organized entity.
+
+“Control” means direct or indirect ownership of more than fifty percent of an
+entity’s voting interests or the power to direct its management or policies.
+
+“Group” means an Organization together with every entity that Controls, is
+Controlled by, or is under common Control with it.
+
+“Modified Version” means a work that copies, adapts, translates, ports, or
+modifies protected expression from the Covered Materials in a manner requiring
+permission under applicable law.
+
+“Library Functionality” means:
+
+1. providing a client SDK for encrypted ULDA resources and catalogs;
+2. preparing and verifying encrypted resource containers while coordinating
+   per-resource ULDA state through the underlying core;
+3. exposing client data access, resource lifecycle, and write queues; and
+4. managing client transport, change delivery, and connection recovery for
+   those resources.
+
+These definitions describe the SDK as an integrated product. They do not
+relicense the separately distributed `ulda-core` or claim exclusive rights
+over general encryption, networking, or programming techniques.
+
+“Functionally Equivalent Offering” means a product or service whose entire or
+primary purpose is to provide all or a material part of the Library Functionality
+as:
+
+- a standalone ULDA client library or SDK;
+- a port, replacement, or substantial substitute for `ulda-auth`; or
+- a hosted service or API that exposes that functionality directly to third
+  parties.
+
+“Ancillary Application” means a larger application whose primary purpose is
+materially different from the Library Functionality and which uses ULDA only as a
+supporting component for encrypted application data, integrity, lineage, or
+resource synchronization.
+
+An Ancillary Application does not become a Functionally Equivalent Offering
+merely because it calls the public `ulda-auth` API or includes an official
+bundle.
+
+## 3. Community license
+
+Subject to this License, each Licensor grants You, only to the extent of the
+rights controlled by that Licensor, a worldwide, royalty-free, non-exclusive,
+non-transferable, and non-sublicensable copyright license to:
+
+- use and run the Covered Materials;
+- inspect and study them;
+- copy and modify them;
+- create private forks and Modified Versions;
+- embed them in an Ancillary Application;
+- distribute them in source or bundled form;
+- use them in paid products and services; and
+- provide them as part of a hosted Ancillary Application.
+
+You may exercise these permissions if:
+
+1. You are an individual acting solely for personal, educational, research, or
+   other non-commercial purposes; or
+2. You are a Qualifying Small Organization under Section 4.
+
+Commercial use is permitted for a Qualifying Small Organization.
+
+You may keep modifications and the source code of an Ancillary Application
+private. This License does not impose a source-publication requirement.
+
+Every recipient must independently qualify under this License or obtain a
+separate commercial license.
+
+An end user who merely accesses an Ancillary Application and does not deploy,
+integrate, modify, distribute, or use the Covered Materials separately does not
+need to qualify independently merely because the Covered Materials are
+delivered to or executed on that end user’s device.
+
+Creating and maintaining a private Modified Version solely to integrate,
+operate, secure, or maintain a permitted Ancillary Application does not by
+itself create a Functionally Equivalent Offering. Offering or distributing
+that Modified Version as a standalone ULDA client library or SDK remains subject to
+Section 5.
+
+## 4. Revenue threshold
+
+The “Revenue Threshold” is **USD 1,000,000**.
+
+“Consolidated Gross Revenue” means the total worldwide gross revenue or gross
+receipts of the Group before deducting costs, operating expenses, owner
+compensation, contractor payments, or distributions. Bona fide transactions
+between Group members must be eliminated to avoid counting the same revenue
+twice.
+
+Revenue must be calculated using the accounting standards legally required
+for the Organization’s consolidated financial statements. If no such
+standards apply, the Organization must use the method reflected in its
+official tax filings or externally prepared financial statements. If none
+exist, it must use a reasonable and consistently applied method based on its
+ordinary books and records.
+
+An accounting method, fiscal year, revenue classification, or business
+arrangement must not be selected or changed primarily to avoid the Revenue
+Threshold.
+
+Taxes collected solely for a government, bona fide loans, equity investments,
+and capital contributions are excluded. For each fiscal year tested under this
+Section, an Organization that has no reportable gross revenue or gross receipts
+must use its approved operating budget for that fiscal year.
+
+Amounts recorded in a currency other than United States dollars must be
+converted using the average European Central Bank reference rate for the
+applicable period or, if unavailable, another comparable official central-bank
+rate.
+
+A “Qualifying Small Organization” is an Organization whose Consolidated Gross
+Revenue:
+
+1. did not exceed the Revenue Threshold during its most recently completed
+   fiscal year; and
+2. has not exceeded the Revenue Threshold during its current fiscal year to
+   date.
+
+If no fiscal year has been formally adopted, the calendar year applies. An
+Organization that has not completed its first fiscal year is tested using its
+current fiscal-year-to-date Consolidated Gross Revenue.
+
+A freelancer or individual performing paid work is treated as an Organization
+whether or not the activity is formally registered. Their revenue includes
+gross receipts from all business and professional activities, but excludes
+salary from unrelated employment. When the Covered Materials are used for an
+employer or customer, that employer or customer must independently qualify or
+hold a commercial license.
+
+Revenue or activity must not be divided, concealed, transferred, or
+recharacterized through members of the Group, contractors, accounts,
+deployments, or other arrangements primarily to avoid the Revenue Threshold.
+Affected revenue will be counted as though the arrangement had not occurred.
+
+### Crossing the threshold
+
+“Threshold Crossing Date” means the date on which an Organization that
+previously qualified under this License first exceeds the Revenue Threshold.
+
+Only an Organization that qualified immediately before its Threshold Crossing
+Date receives 90 calendar days to obtain a commercial license or stop
+exercising rights under this License.
+
+Compliant earlier use does not become retroactively unlawful, and no
+retroactive fee is imposed solely because the threshold was crossed.
+
+The 90-day period does not apply to intentional concealment or material
+misrepresentation of revenue, Control, or Group membership.
+
+An Organization that already exceeds the Revenue Threshold when it first
+exercises rights under this License must obtain a commercial license before
+doing so.
+
+### Returning below the threshold
+
+An Organization may qualify again from the first day of a fiscal year if:
+
+1. its Consolidated Gross Revenue remained at or below the Revenue Threshold
+   throughout the immediately preceding completed fiscal year;
+2. it remains at or below the threshold in the current fiscal year to date;
+   and
+3. it otherwise complies with this License.
+
+Requalification applies prospectively. It does not cure a previous violation,
+cancel an amount already due, or automatically terminate or modify an existing
+commercial agreement. That agreement continues according to its own terms.
+
+## 5. Functionally equivalent and competitive uses
+
+Regardless of revenue, You must not use the Covered Materials or a Modified
+Version as development, reference, training, comparison, testing,
+benchmarking, validation, certification, debugging, documentation,
+maintenance, or improvement material to create or provide a Functionally
+Equivalent Offering without a separate written commercial license.
+
+In particular, without such a license You must not:
+
+1. use, modify, translate, port, or adapt the Covered Materials to develop a
+   Functionally Equivalent Offering;
+2. use the Manifest, protocol documentation, examples, or test vectors to
+   develop or validate a Functionally Equivalent Offering;
+3. distribute, license, sell, host, or otherwise provide a Functionally
+   Equivalent Offering developed through a prohibited use of the Covered
+   Materials; or
+4. knowingly enable or assist another person to do any of the foregoing.
+
+This restriction applies even when the competing implementation:
+
+- is written in another programming language;
+- uses a different internal architecture;
+- has different public names or branding; or
+- provides a material part of the Library Functionality sufficient to act as a
+  replacement or substantial substitute for `ulda-auth`.
+
+This Section does not prohibit:
+
+- ordinary use of `ulda-auth` inside an Ancillary Application;
+- testing that an Ancillary Application correctly integrates the official
+  package;
+- private security research that is not used to provide a Functionally
+  Equivalent Offering;
+- unchanged redistribution of an official `ulda-auth` artifact in compliance
+  with Section 6; or
+- acts that applicable mandatory law does not permit this License to restrict.
+
+For clarity, this License does not claim copyright ownership over an abstract
+idea, mathematical principle, algorithm, interface, protocol behavior, or
+functionality as such.
+
+Similar output or behavior alone does not establish that the Covered Materials
+were copied or used.
+
+An implementation independently created without copying or adapting protected
+expression from the Covered Materials, and without exercising permissions
+granted under this License to develop, test, validate, or improve that
+implementation, is not restricted by this License merely because it provides
+similar functionality.
+
+## 6. Distribution and notices
+
+When distributing Covered Materials or a Modified Version, You must:
+
+1. provide this License or an accessible link to it;
+2. preserve copyright, authorship, attribution, and license notices;
+3. identify materially modified files or portions; and
+4. not represent a modified product as an official ULDA release.
+
+For an embedded or minified bundle, notices may be provided in accompanying
+documentation or a `LICENSE`, `NOTICE`, or `ABOUT` file. You are not required
+to extract the bundle or publish the source code of the larger application.
+
+Notwithstanding Sections 3 and 4 and the preceding notice requirements, GitHub,
+npm, jsDelivr, unpkg, registries, mirrors, archives, proxies, security scanners,
+and caches may store, inspect, cache, and transmit unchanged official artifacts
+when the official package or release metadata provides an accessible link to
+this License. This technical permission does not grant a recipient any right to
+use the Covered Materials beyond the other terms of this License and does not
+authorize a Functionally Equivalent Offering.
+
+No rights to ULDA names, logos, trademarks, service marks, or other branding
+are granted except accurate descriptive references that do not imply
+endorsement, certification, or official status.
+
+## 7. Commercial licensing, ownership, and other rights
+
+A separate written commercial license is required:
+
+1. after the Revenue Threshold transition period;
+2. for a Functionally Equivalent Offering; or
+3. for any use outside this License.
+
+A commercial license covering all Covered Materials may be granted only by
+Mark Shaposhnik and Vitalii Radko jointly, or by a person or legal entity
+authorized in writing by each Licensor to license that Licensor’s respective
+rights.
+
+Commercial licensing inquiries may be sent to
+[mark@shaposhnik.ch](mailto:mark@shaposhnik.ch). This address is an
+administrative contact only. Correspondence does not itself grant any rights;
+commercial rights arise only under a separate written agreement granted as
+described above.
+
+A future company may administer community and commercial licensing only after
+receiving the necessary rights or licensing authority through a separate
+written agreement. Such a transfer or authorization does not terminate or
+narrow licenses already validly granted.
+
+Commercial pricing, support, warranties, service levels, and payment terms are
+governed by the separate agreement.
+
+This License grants no patent license. It also grants no rights in future ULDA
+products or other separately distributed products except as expressly stated.
+All rights not expressly granted are reserved.
+
+## 8. Termination and general terms
+
+If You violate this License, Your rights continue if You fully cure the first
+notified violation within 30 days.
+
+An uncured violation, repeated material violation, or intentional material
+misrepresentation terminates Your rights. Crossing the Revenue Threshold is
+governed by the 90-day period in Section 4.
+
+Upon termination, You must stop using and distributing the Covered Materials.
+Rights of recipients who independently comply with this License are not
+terminated solely because Your rights ended.
+
+THE COVERED MATERIALS ARE PROVIDED “AS IS” AND “AS AVAILABLE,” WITHOUT
+WARRANTIES OF ANY KIND, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, SECURITY, ACCURACY, OR RELIABILITY.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSORS WILL NOT BE LIABLE FOR
+INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES,
+OR FOR LOSS OF PROFITS, REVENUE, DATA, BUSINESS, OR GOODWILL.
+
+THE LICENSORS’ TOTAL AGGREGATE LIABILITY WILL NOT EXCEED THE AMOUNT PAID
+DIRECTLY FOR USE OF THE COVERED MATERIALS DURING THE TWELVE MONTHS BEFORE THE
+CLAIM. IF NOTHING WAS PAID, THE LIMIT IS ZERO TO THE MAXIMUM EXTENT PERMITTED
+BY LAW.
+
+This License is governed by Swiss law, excluding conflict-of-law rules.
+Disputes are subject to the competent courts in Switzerland unless a separate
+written agreement provides otherwise.
+
+If any provision is unenforceable, it will be enforced to the maximum extent
+permitted, and the remaining provisions remain effective. Failure to enforce a
+provision is not a waiver.
+
+A signed commercial agreement controls where it expressly conflicts with this
+License.
+
+The warranty disclaimers, liability limitations, governing-law and dispute
+provisions, and obligations accrued before termination survive termination.
+
+The Licensors may publish new versions of this License. A release remains
+governed by the version distributed with that release unless You and the
+applicable Licensors agree otherwise in writing. A new version does not
+retroactively change the terms governing an earlier release.
+
+---
+
+**End of ULDA Library Community Source License 1.0**

package/MANIFEST.md

@@ -0,0 +1,100 @@
+# ULDA Auth Manifest
+
+This manifest defines the SDK's architecture, data model and supported contract. Usage examples are in the [guide](docs/GUIDE.md); security assumptions are in [SECURITY.md](SECURITY.md).
+
+## Purpose
+
+ULDA Auth is a JavaScript client SDK for encrypted JSON resources. It manages an encrypted catalog, a separate ULDA chain per resource, client-side encryption, write queues, transport, change delivery and connection recovery.
+
+It uses the separately licensed `ulda-core@1.0.1`. The application supplies its endpoint, master ID and password. The storage server, account UI and application authorization are separate components.
+
+## Components
+
+| Component | Responsibility |
+|---|---|
+| Client | Catalog, resource lifecycle, validated local state and event delivery |
+| Crypto | Password/content key derivation and authenticated encryption |
+| Core adapter | Supported ULDA profile, origin creation, chain advancement and witness verification |
+| Protocol | Exact packet shapes, size validation and opaque outgoing handles |
+| Transport | One Socket.IO WebSocket connection, ACKs and incoming encrypted records |
+| Queues | Per-resource X/S writes and serialized catalog operations |
+| Reconnect | Bounded connection/Hello/read retries, without write replay |
+| References | Explicit access to application JSON through get/update/delete |
+
+`src/` contains the JavaScript implementation. `dist/ulda-library.js` is the generated standalone ESM bundle. `types/index.d.ts` describes the same API for editors and TypeScript; it is not another runtime implementation.
+
+## Resource model
+
+A master is an encrypted catalog containing content IDs, names, secrets and identity tokens. It always uses X. Content stores application JSON and uses X by default, or S when chosen at creation.
+
+A server record contains only `id`, `witness` and encrypted `payload`. It has no explicit master/content role or parent field. The client interprets its decrypted catalog; the server can still observe access patterns and public witness metadata.
+
+Public snapshots expose application JSON, not internal catalog credentials or origins.
+
+## Supported profile
+
+| Property | Value |
+|---|---|
+| Core format | canonical compactV1 |
+| Core hash | SHA-256 |
+| Chain width | N=5 |
+| Origin block size | 256 bits |
+| Modes | X and S |
+| Age | uint32; advancing past the maximum is rejected |
+| Payload container | SDK version 2 |
+| Encryption | AES-256-GCM, 96-bit nonce, 128-bit tag |
+| Master KDF | PBKDF2-HMAC-SHA-256, 600000 iterations, 16-byte salt |
+| Content KDF | HKDF-SHA-256, independent 32-byte secret, 16-byte salt |
+| AES key export | Disabled |
+
+The header and full witness are authenticated with the encrypted payload. The [protocol specification](docs/PROTOCOL.md) defines byte layout and domain separation.
+
+## Operational contract
+
+One SDK instance uses one connection. Successful Read/Create/Update subscribes it before ACK. Its own write is confirmed by ACK; other subscribers receive Changed. Disconnect removes subscriptions.
+
+Content creation reserves an ID, then atomically updates the content and master together. The two commits are not one distributed transaction. Update batches and mixed Delete/Update batches must be atomic at the compatible server.
+
+Conflicting writers do not merge. X permits one pending write per resource. S permits a bounded local chain of pending writes. Every operation retains its own ACK/outcome.
+
+Writes are volatile and are not replayed automatically. Missing or invalid success ACKs produce UNKNOWN_OUTCOME. Explicit refresh may resolve working state without changing the original rejected promise.
+
+Live updates require a valid chain transition. Full refresh/reconnect may accept an authenticated newer snapshot without missing intermediate history. The server's selection of that snapshot and its deletion notifications are trusted. Invalid input preserves verified local state and blocks normal writes.
+
+Explicit content recovery creates a new resource from a confirmed local copy, replaces one catalog entry and keeps the old resource.
+
+## Interfaces
+
+Exports: `Ulda`, `SocketIoTransport` and `UldaError`.
+
+The client provides registration/opening, CRUD, nested references, local snapshots, refresh, reconnect, explicit recovery, close, and status/change/error/trace/reconnect events. Signatures and error behavior are defined in [API.md](docs/API.md).
+
+## Limits
+
+| Limit | Value |
+|---|---|
+| Application JSON per resource | 1,048,576 UTF-8 bytes |
+| JSON nesting depth | 48 |
+| Visited JSON nodes | 40,000 |
+| Content entries per master | 63 |
+| Items per protocol batch/event | 64 |
+| Combined witness/payload bytes per message | 8,388,608 |
+| Binary attachments per Socket.IO packet | 128 |
+| Bytes per binary attachment | 1,100,000 |
+| Decoder text header | 65,536 UTF-8 bytes |
+| Queued incoming handlers | 8 |
+| Waiting/pending jobs per relevant outgoing queue | 128 |
+| Content name | 1–256 UTF-16 code units |
+| Master password input | 1–1024 UTF-16 code units |
+
+Container overhead and catalog metadata consume additional space; not every theoretical maximum can necessarily be combined in one batch. Oversized Read requests can be split into smaller groups. Atomic writes are not split.
+
+## Environment and distribution
+
+Node.js 22 or later; browser ES2022 with Web Crypto and WebSocket in a secure context. HTTPS endpoints are required except explicit HTTP loopback development.
+
+The normal ESM entry uses npm dependencies. The browser ESM bundles them and includes their license notices. The package contains runtime modules, declarations, the browser bundle and user documentation. Test fixtures and maintainer tooling are repository-only.
+
+Private fields, non-extractable keys and best-effort cleanup do not isolate secrets from hostile code controlling the same page or process. [Secret lifecycle](docs/SECRET_LIFECYCLE.md) defines cleanup responsibilities.
+
+The [ULDA Library Community Source License](LICENSE.md) governs the SDK. Dependencies retain their own licenses; the core and server have separate scopes.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# ULDA Auth
 
-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.
+A JavaScript SDK for encrypted JSON resources over Socket.IO, built on [ULDA Core](https://github.com/ulda-io/ulda-core).
+
+ULDA Auth encrypts application data on the client, maintains a separate ULDA chain for each resource, and synchronizes changes across connected clients. Applications work with JSON and explicit update methods.
+
+## Install
+
+~~~sh
+npm install ulda-auth
+~~~
+
+Requires Node.js 22 or later, or a browser with ES2022, Web Crypto and WebSocket support. Use an HTTPS endpoint running a compatible [ULDA protocol](docs/PROTOCOL.md) server. A generic Socket.IO server is not sufficient.
+
+The package provides ES modules. JavaScript is the runtime implementation; TypeScript declarations are included for editor assistance and typed applications.
+
+## Quick start
+
+The application supplies the server URL and a password obtained from the user.
+
+~~~js
+import { Ulda } from 'ulda-auth';
+
+export async function createNotebook(endpoint, password) {
+  const ulda = new Ulda(endpoint);
+
+  try {
+    await ulda.ready;
+    const masterId = await ulda.register(password);
+
+    await ulda.add('notes', { title: 'First note', done: false });
+    await ulda.data.notes.title.update('Updated title');
+
+    const note = ulda.value('notes'); // An independent JSON copy.
+    return { masterId, note };
+  } finally {
+    await ulda.close();
+  }
+}
+~~~
+
+Keep the returned master ID: it identifies the encrypted catalog needed to reopen the data. Store and present it through your application. ULDA Auth does not provide usernames, password reset or an account directory.
+
+To open an existing catalog:
+
+~~~js
+import { Ulda } from 'ulda-auth';
+
+export async function openNotebook(endpoint, masterId, password) {
+  const ulda = new Ulda(endpoint);
+  try {
+    await ulda.connect(masterId, password);
+    return ulda; // The caller owns this session and must close it when finished.
+  } catch (error) {
+    await ulda.close();
+    throw error;
+  }
+}
+~~~
+
+Resource IDs are decimal **strings**, not JavaScript numbers.
+
+## Working with data
+
+~~~js
+const notes = ulda.ref('notes');
+
+const title = notes.title.get();
+await notes.title.update('Another title');
+await ulda.set('notes', ['done'], true);
+
+// Editing a returned copy does not write to the server.
+const copy = ulda.snapshot();
+
+const unsubscribe = ulda.on('change', () => {
+  const current = ulda.snapshot();
+  // Render or otherwise use the current application data.
+});
+
+// Later:
+unsubscribe();
+await ulda.close();
+~~~
+
+References are explicit: use `.get()` to read a value and await `.update()` or `.delete()` to change it. Assigning to a reference does not save data and is rejected.
+
+## Resource model
+
+A **master** is an encrypted catalog of content IDs, names and secrets. A **content** resource holds application JSON. Each has its own encryption material and ULDA chain.
+
+The server stores `id`, public `witness` and encrypted `payload`. Content names, catalog entries, application JSON and the full origin remain inside encrypted containers. IDs, lengths, witness metadata and traffic patterns remain visible.
+
+Successful Create, Read and Update operations subscribe the connection to changes. The initiating connection receives an ACK; other subscribed connections receive updates. Disconnecting clears subscriptions, which are rebuilt by reading after reconnect.
+
+## Concurrency and failures
+
+- Mode **X**, the default, waits for an acknowledgement before sending the next write for that resource. Mode **S** allows a bounded sequence of pending writes.
+- Conflicting writers do not merge automatically. Refresh, inspect the current data, and decide whether to apply the intended change again.
+- A timeout after sending a write can produce `UNKNOWN_OUTCOME`: the server may have committed it. The SDK never automatically replays writes.
+- Creating content uses two server commits: reserve its ID, then atomically update the content and master. An interrupted operation can leave an unreferenced encrypted resource.
+- Reconnect retries are bounded. There is no persistent offline write queue.
+
+See the [usage guide](docs/GUIDE.md) for errors, reconnect, deletion and recovery. Read the [security policy](SECURITY.md) before integrating sensitive data.
+
+## Browser entry
+
+With a bundler:
+
+~~~js
+import { Ulda } from 'ulda-auth/browser';
+~~~
+
+This entry bundles the core and Socket.IO dependencies. Without a bundler, host `dist/ulda-library.js` with the accompanying license notices and import it from your own page using `<script type="module">`. Bare npm package names require a bundler or import map.
+
+## Documentation
+
+- [Usage guide](docs/GUIDE.md) — complete workflows and examples.
+- [API reference](docs/API.md) — methods, options, events and errors.
+- [Protocol](docs/PROTOCOL.md) — socket events, binary records and server requirements.
+- [Method pipelines](docs/PIPELINES.md) — internal steps for each operation.
+- [Content recovery](docs/RECOVERY.md) — explicit replacement from a verified local copy.
+- [Secret lifecycle](docs/SECRET_LIFECYCLE.md) — storage and cleanup in memory.
+- [Manifest](MANIFEST.md) — architecture, supported profile and limits.
+- [Security](SECURITY.md) — reporting vulnerabilities and the trust model.
+
+For repository tooling, see [development](https://github.com/ulda-io/ulda-auth/blob/main/docs/DEVELOPMENT.md) and [publishing](https://github.com/ulda-io/ulda-auth/blob/main/docs/PUBLISHING.md).
+
+## License
+
+[ULDA Library Community Source License 1.0](LICENSE.md), a source-available license with revenue and competitive-use conditions. Commercial licensing: [mark@shaposhnik.ch](mailto:mark@shaposhnik.ch).
+
+See the [licensing guide](docs/LICENSING.md) for a summary. Dependencies retain their own licenses.