@voltro/plugin-auth 0.85.0 → 0.87.0

package/README.md

@@ -20,7 +20,100 @@ Installation, guides, the full API reference, and examples all live in the
 **[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
 deliberately short so there is nothing here to drift out of date.
 
+The opt-in `auth.guest` extension adds durable guest device credentials and
+registered sessions. Its current status is **built**; see [Guest
+identities](https://docs.voltro.dev/docs/authentication/guests) for the storage
+contract, trusted transaction-bound account upgrade and remaining validation
+limits.
+
+`@voltro/plugin-auth/guest` provides the same guest client and pure credential
+parser without React or server imports. Possession remains a server SQL check.
+
+`@voltro/plugin-auth/native` also exports `nativeGuestStore`: adapt a supplied
+durable native store and host-wide lock without a memory fallback. Create and
+Resume responses bind the guest subject to the device proof before exposing
+the session or persisting a new proof. Real OS-keystore verification remains
+separate from the port contract.
+
+## Registered device sessions
+
+`rotateRegisteredSession` replaces a credential atomically and retains inactive
+aliases so revoking an earlier cookie's row also ends its successor. Registry
+writes own transactions; use `{ transaction: 'existing' }` inside a mutation or
+an explicit transaction. Apply the declared `sessions` schema before restarting
+upgraded auth replicas. See the bilingual
+[session guide](https://docs.voltro.dev/docs/authentication/sessions) for authority
+checks, device families and revocation cache limits.
+
+`lockRegisteredSession(store, userId, sessionId)` reads an owned, unrotated
+credential under the device-family fence. Supply the store of an existing
+transaction, after the application's account/tenant fences, and keep that
+transaction through the protected write. The helper does not validate a signed
+token, expiry or application permissions. Root and presented-row locking reads
+also serve rotation, touch and family revocation; ordinary reads and zero cache
+TTL are not a substitute for native transaction semantics.
+
 ## License
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+
+
+### Complete device-family root discovery
+
+Account-wide DataStore registry revocation locks actual user-owned family roots
+in stable order before descendant rows. It never enumerates roots through an
+ordinary older snapshot or rediscoveries after the current-root query. Revoke-other-
+devices resolves its preserved lineage after acquiring the root roster, including
+an owned rotation alias; unknown/foreign keep IDs retain no unverified family.
+
+For an existing transaction, real owner/account fences must precede the registry's
+family fences. New-root issuance must change the same actual owner's persisted
+revision atomically with registration when an older repeatable-read snapshot is
+possible. PostgreSQL row locking alone does not refresh that snapshot. Applications
+owe whole-transaction retry/abort, not a cache workaround or fabricated owner.
+Cloud implements this with private users.sessionFamilyRevision and its existing
+account lifecycle fence. Other custom registries/issuers owe their equivalent
+native contract. Native dialect/rollback/concurrency/replica/restart proof remains
+required. Stop old issuers and apply declared schema before coordinated cutover.
+
+
+### Session reads require the owned canonical family root
+
+`findSession` and `listSessions` return only unrotated credentials whose canonical
+family root exists and has the same `userId`. A rotated root is still a valid
+anchor; its tenant and expiry do not replace those of the current credential.
+Missing, foreign or chained roots are refused without reconstructing any row.
+Custom `SessionStore` implementations must enforce this read contract too.
+Registry and Memory reads reject ambiguous duplicate IDs. PostgreSQL uses a
+single self-join on the actual sessions table for each lookup/enumeration.
+Memory insert/read results copy stored dates rather than exposing mutable
+references. These reads are point-in-time eligibility checks, not a replacement
+for locked current-session validation inside a protected write transaction.
+Positive revocation-cache entries still obey the configured TTL; choose the
+required revocation window explicitly.
+
+
+### Bind a revocation check to the signed user
+
+`makeSessionRevocationChecker(store, options).isLiveFor(sessionId, userId)`
+requires the verified signed user's ID. A live credential owned by another
+user is refused. The cached entry retains the actual row owner; checking a
+wrong user neither authorizes that user nor poisons the owner's verdict.
+`invalidate(sessionId)` clears that credential regardless of requested user.
+Positive freshness is capped by both TTL and observed row expiry.
+
+`SessionRevocationChecker` implementers must provide `isLiveFor`, `invalidate`
+and a finite nonnegative `ttlMs`. The ownerless `isLive` method is removed;
+unsupported objects fail construction rather than becoming cache options.
+Options accept only finite nonnegative `ttlMs`, nonnegative safe-integer
+`maxEntries` and a `now` clock function. Zero `maxEntries` disables caching.
+Normal HTTP auth, carried strategies and Cloud reauthorization/renewal pass
+the verified subject ID. Native root ownership, current account authorization
+and protected write fences remain separate requirements. Existing signed
+payloads and session schemas do not change. Run `voltro update` to receive the
+manual migration instructions for custom checker calls and implementations.
+
+With `requireSessionId: true`, a missing checker fails authentication even if
+the signed payload carries an ID. Wire a store, registry or conforming checker;
+the flag alone does not prove a persisted session.