@oxyhq/core 20.0.0 → 21.0.0

package/dist/esm/boot/sessionColdBoot.js

@@ -15,10 +15,17 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
- *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
- *      re-mint from THIS device's primary identity key.
- *   4. Signed out.
+ *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
+ *      of its own but a sibling official app already put one in the shared native
+ *      slot: adopt it and mint. This is how a newly installed official app joins
+ *      the device's existing session WITHOUT another QR and without ever touching
+ *      the Commons private key.
+ *   4. `shared-key-signin` (native, ACCOUNT mode) — the legacy lane: re-mint by
+ *      signing with the shared-keychain IDENTITY key. Retained as a recovery /
+ *      compatibility path for devices whose apps have not yet published a shared
+ *      device credential — OR `identity-key-signin` (IDENTITY mode) — re-mint
+ *      from THIS device's primary identity key.
+ *   5. Signed out.
  *
  * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
  *   - `account` (default) — the device's ACTIVE account owns the session. Every
@@ -37,6 +44,7 @@ import { logger } from '../logger/index.js';
 import { computeIdentityTag } from '../utils/cacheKey.js';
 import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh.js';
 import { establishIdentitySession, resolveIdentityPin, } from '../session/identitySession.js';
+import { decideSharedDeviceJoin, } from '../session/sharedDeviceCredential.js';
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted) or
@@ -236,10 +244,101 @@ export async function runSessionColdBoot(opts) {
             },
         });
     }
-    else {
-        // 3. shared-key-signin (native) — re-mint from the shared identity. Native
-        //    AND online: it is a network step (challenge + verify round-trips), so it
-        //    is gated by the same offline hint as the mint lane. `{ retry: false }`
+    else if (opts.sharedDeviceCredential) {
+        // 3. shared-device-adopt (native, ACCOUNT mode) — join the device's existing
+        //    session through the shared native credential slot.
+        //
+        //    This is the lane that separates identity from session transport. What it
+        //    reads is an ordinary, individually revocable `deviceId` + `deviceSecret`
+        //    put there by a sibling official app — never the Commons private key. It
+        //    is what lets a freshly installed official app land signed in with no QR,
+        //    and it is why an ordinary app never needs identity-key access at all.
+        //
+        //    `decideSharedDeviceJoin` gates it: an app that already holds its own
+        //    credential is never moved, and an UNREADABLE slot is never mistaken for
+        //    an empty one. The lane therefore cannot sign anyone out, in either
+        //    upgrade order.
+        const sharedSlot = opts.sharedDeviceCredential;
+        steps.push({
+            id: 'shared-device-adopt',
+            // The adoption itself is local, but it is only worth committing alongside
+            // a mint that proves the credential — so the whole lane is online-gated
+            // like every other network step.
+            enabled: () => isNative && !isOffline(),
+            run: async () => {
+                const before = await store.load();
+                const decision = decideSharedDeviceJoin(before, await sharedSlot.read());
+                if (decision.action === 'skip') {
+                    logger.debug(`shared device credential not adopted (${decision.reason})`, { component: 'sessionColdBoot', method: 'shared-device-adopt' });
+                    return { kind: 'skip' };
+                }
+                // Restore the store to exactly what it held before this lane touched it.
+                // A credential we adopted and could not prove must not be left behind for
+                // the next boot's mint lane to keep retrying.
+                const revert = async () => {
+                    if (before) {
+                        await store.save(before);
+                    }
+                    else {
+                        await store.clear();
+                    }
+                };
+                const adopted = {
+                    // The mint fills both in from the device's live state; carrying the
+                    // previous session's ids into a different device session would be a
+                    // lie for however long the mint takes.
+                    sessionId: '',
+                    userId: '',
+                    deviceId: decision.credential.deviceId,
+                    deviceSecret: decision.credential.deviceSecret,
+                };
+                if (!(await store.save(adopted))) {
+                    logger.error('adopted the shared device credential but it could not be durably persisted — reverting', undefined, { component: 'sessionColdBoot', method: 'shared-device-adopt' });
+                    await revert();
+                    return { kind: 'skip' };
+                }
+                const result = await refreshDeviceSecretArm({ oxy, store, pin: null });
+                if (result.status === 'ok') {
+                    return {
+                        kind: 'session',
+                        session: {
+                            sessionId: result.sessionId,
+                            userId: result.userId,
+                            accessToken: result.token,
+                        },
+                    };
+                }
+                if (result.status === 'invalid-secret') {
+                    // The one place we hold POSITIVE proof that the exact bytes in the
+                    // shared slot are dead — the server rejected them by name. Clearing it
+                    // signs nobody out (a credential the server does not recognise cannot
+                    // be minting for anyone) and it is what stops a dead credential from
+                    // blocking every future install: a stale slot owned by a different
+                    // `deviceId` is otherwise never overwritten, by design.
+                    await sharedSlot.clear();
+                }
+                else if (result.status === 'no-session') {
+                    signedOutReason = 'no_session';
+                }
+                await revert();
+                return { kind: 'skip' };
+            },
+        });
+    }
+    if (identityBinding === null) {
+        // 4. shared-key-signin (native) — the RECOVERY / COMPATIBILITY lane: sign a
+        //    challenge with the shared-keychain IDENTITY key to re-mint a session.
+        //
+        //    It runs LAST on purpose. Using the self-custody key to obtain an ordinary
+        //    session is the over-sharing #937 sets out to end, so it is now reachable
+        //    only on a device where no sibling app has published a shared device
+        //    credential yet — an install that predates this lane, or one where the
+        //    shared slot is unreadable. Its own `store.save` below feeds the shared
+        //    slot through the mirroring store, so the FIRST boot that takes this lane
+        //    is also the last one that needs to: every later app joins by credential.
+        //
+        //    Native AND online: it is a network step (challenge + verify round-trips),
+        //    so it is gated by the same offline hint as the mint lane. `{ retry: false }`
         //    keeps the two round-trips as single attempts — the refresh scheduler /
         //    401 lane own later retries — so this step cannot multiply boot latency.
         steps.push({

package/dist/esm/i18n/locales/en-US.json

@@ -396,13 +396,22 @@
             "remoteSignOutFailed": "There was a problem signing out from the device. Please try again.",
             "noOtherDeviceSessions": "No other device sessions found to sign out from.",
             "signOutOthersSuccess": "Signed out from all other devices successfully!",
-            "signOutOthersFailed": "There was a problem signing out from other devices. Please try again."
+            "signOutOthersFailed": "There was a problem signing out from other devices. Please try again.",
+            "contextRemoved": "Removed {{account}}",
+            "contextRemoveFailed": "There was a problem removing that account. Please try again.",
+            "principalRemoved": "Signed {{name}} out of this device",
+            "principalRemoveFailed": "There was a problem signing that person out. Please try again.",
+            "activateFailed": "There was a problem switching accounts. Please try again."
         },
         "confirms": {
             "remove": "Are you sure you want to remove {{displayName}} from this device? You'll need to sign in again to access this account.",
             "logoutAll": "Are you sure you want to sign out of all accounts? This will remove all saved accounts from this device.",
             "remoteLogout": "Are you sure you want to sign out from \"{{deviceName}}\"? This will end the session on that device.",
-            "logoutOthers": "Are you sure you want to sign out from all {{count}} other device(s)? This will end sessions on all other devices except this one."
+            "logoutOthers": "Are you sure you want to sign out from all {{count}} other device(s)? This will end sessions on all other devices except this one.",
+            "removeContextTitle": "Remove this account?",
+            "removeContext": "Stop {{person}} acting as {{account}} on this device? Anyone else who reaches {{account}} here keeps their access.",
+            "removePrincipalTitle": "Sign out of this device?",
+            "removePrincipal": "Sign {{name}} out of this device? Every account they reach here is removed. Nobody else is affected."
         },
         "device": {
             "loadingTitle": "Loading device sessions...",
@@ -439,6 +448,14 @@
             "openedInCommons": "Opened in Commons",
             "confirming": "Confirming identity",
             "confirmed": "Identity confirmed"
+        },
+        "context": {
+            "unavailable": "Unavailable right now",
+            "operatedBy": "Operated by {{name}}",
+            "remove": "Remove {{account}} from {{person}}"
+        },
+        "principal": {
+            "signOut": "Sign {{name}} out of this device"
         }
     },
     "reputation": {

package/dist/esm/i18n/locales/es-ES.json

@@ -636,13 +636,22 @@
             "remoteSignOutFailed": "Hubo un problema al cerrar sesión en el dispositivo. Inténtalo de nuevo.",
             "noOtherDeviceSessions": "No se encontraron otras sesiones de dispositivo para cerrar.",
             "signOutOthersSuccess": "¡Sesiones cerradas correctamente en los demás dispositivos!",
-            "signOutOthersFailed": "Hubo un problema al cerrar sesión en otros dispositivos. Inténtalo de nuevo."
+            "signOutOthersFailed": "Hubo un problema al cerrar sesión en otros dispositivos. Inténtalo de nuevo.",
+            "contextRemoved": "Se quitó {{account}}",
+            "contextRemoveFailed": "Hubo un problema al quitar esa cuenta. Inténtalo de nuevo.",
+            "principalRemoved": "Se cerró la sesión de {{name}} en este dispositivo",
+            "principalRemoveFailed": "Hubo un problema al cerrar esa sesión. Inténtalo de nuevo.",
+            "activateFailed": "Hubo un problema al cambiar de cuenta. Inténtalo de nuevo."
         },
         "confirms": {
             "remove": "¿Seguro que quieres eliminar a {{displayName}} de este dispositivo? Tendrás que iniciar sesión de nuevo para acceder a esta cuenta.",
             "logoutAll": "¿Seguro que quieres cerrar sesión en todas las cuentas? Esto eliminará todas las cuentas guardadas de este dispositivo.",
             "remoteLogout": "¿Seguro que quieres cerrar sesión en \"{{deviceName}}\"? Esto finalizará la sesión en ese dispositivo.",
-            "logoutOthers": "¿Seguro que quieres cerrar sesión en los otros {{count}} dispositivo(s)? Esto finalizará las sesiones en todos los demás dispositivos excepto en este."
+            "logoutOthers": "¿Seguro que quieres cerrar sesión en los otros {{count}} dispositivo(s)? Esto finalizará las sesiones en todos los demás dispositivos excepto en este.",
+            "removeContextTitle": "¿Quitar esta cuenta?",
+            "removeContext": "¿Dejar de usar {{account}} como {{person}} en este dispositivo? Quien más acceda a {{account}} aquí lo conserva.",
+            "removePrincipalTitle": "¿Cerrar sesión en este dispositivo?",
+            "removePrincipal": "¿Cerrar la sesión de {{name}} en este dispositivo? Se quitan todas las cuentas a las que llega desde aquí. No afecta a nadie más."
         },
         "device": {
             "loadingTitle": "Cargando sesiones de dispositivo...",
@@ -679,6 +688,14 @@
             "openedInCommons": "Abierto en Commons",
             "confirming": "Confirmando identidad",
             "confirmed": "Identidad confirmada"
+        },
+        "context": {
+            "unavailable": "No disponible ahora mismo",
+            "operatedBy": "Gestionada por {{name}}",
+            "remove": "Quitar {{account}} de {{person}}"
+        },
+        "principal": {
+            "signOut": "Cerrar la sesión de {{name}} en este dispositivo"
         }
     },
     "feedback": {

package/dist/esm/i18n/locales/locales/en-US.json

@@ -396,13 +396,22 @@
       "remoteSignOutFailed": "There was a problem signing out from the device. Please try again.",
       "noOtherDeviceSessions": "No other device sessions found to sign out from.",
       "signOutOthersSuccess": "Signed out from all other devices successfully!",
-      "signOutOthersFailed": "There was a problem signing out from other devices. Please try again."
+      "signOutOthersFailed": "There was a problem signing out from other devices. Please try again.",
+      "contextRemoved": "Removed {{account}}",
+      "contextRemoveFailed": "There was a problem removing that account. Please try again.",
+      "principalRemoved": "Signed {{name}} out of this device",
+      "principalRemoveFailed": "There was a problem signing that person out. Please try again.",
+      "activateFailed": "There was a problem switching accounts. Please try again."
     },
     "confirms": {
       "remove": "Are you sure you want to remove {{displayName}} from this device? You'll need to sign in again to access this account.",
       "logoutAll": "Are you sure you want to sign out of all accounts? This will remove all saved accounts from this device.",
       "remoteLogout": "Are you sure you want to sign out from \"{{deviceName}}\"? This will end the session on that device.",
-      "logoutOthers": "Are you sure you want to sign out from all {{count}} other device(s)? This will end sessions on all other devices except this one."
+      "logoutOthers": "Are you sure you want to sign out from all {{count}} other device(s)? This will end sessions on all other devices except this one.",
+      "removeContextTitle": "Remove this account?",
+      "removeContext": "Stop {{person}} acting as {{account}} on this device? Anyone else who reaches {{account}} here keeps their access.",
+      "removePrincipalTitle": "Sign out of this device?",
+      "removePrincipal": "Sign {{name}} out of this device? Every account they reach here is removed. Nobody else is affected."
     },
     "device": {
       "loadingTitle": "Loading device sessions...",
@@ -439,6 +448,14 @@
       "openedInCommons": "Opened in Commons",
       "confirming": "Confirming identity",
       "confirmed": "Identity confirmed"
+    },
+    "context": {
+      "unavailable": "Unavailable right now",
+      "operatedBy": "Operated by {{name}}",
+      "remove": "Remove {{account}} from {{person}}"
+    },
+    "principal": {
+      "signOut": "Sign {{name}} out of this device"
     }
   },
   "reputation": {

package/dist/esm/i18n/locales/locales/es-ES.json

@@ -636,13 +636,22 @@
       "remoteSignOutFailed": "Hubo un problema al cerrar sesión en el dispositivo. Inténtalo de nuevo.",
       "noOtherDeviceSessions": "No se encontraron otras sesiones de dispositivo para cerrar.",
       "signOutOthersSuccess": "¡Sesiones cerradas correctamente en los demás dispositivos!",
-      "signOutOthersFailed": "Hubo un problema al cerrar sesión en otros dispositivos. Inténtalo de nuevo."
+      "signOutOthersFailed": "Hubo un problema al cerrar sesión en otros dispositivos. Inténtalo de nuevo.",
+      "contextRemoved": "Se quitó {{account}}",
+      "contextRemoveFailed": "Hubo un problema al quitar esa cuenta. Inténtalo de nuevo.",
+      "principalRemoved": "Se cerró la sesión de {{name}} en este dispositivo",
+      "principalRemoveFailed": "Hubo un problema al cerrar esa sesión. Inténtalo de nuevo.",
+      "activateFailed": "Hubo un problema al cambiar de cuenta. Inténtalo de nuevo."
     },
     "confirms": {
       "remove": "¿Seguro que quieres eliminar a {{displayName}} de este dispositivo? Tendrás que iniciar sesión de nuevo para acceder a esta cuenta.",
       "logoutAll": "¿Seguro que quieres cerrar sesión en todas las cuentas? Esto eliminará todas las cuentas guardadas de este dispositivo.",
       "remoteLogout": "¿Seguro que quieres cerrar sesión en \"{{deviceName}}\"? Esto finalizará la sesión en ese dispositivo.",
-      "logoutOthers": "¿Seguro que quieres cerrar sesión en los otros {{count}} dispositivo(s)? Esto finalizará las sesiones en todos los demás dispositivos excepto en este."
+      "logoutOthers": "¿Seguro que quieres cerrar sesión en los otros {{count}} dispositivo(s)? Esto finalizará las sesiones en todos los demás dispositivos excepto en este.",
+      "removeContextTitle": "¿Quitar esta cuenta?",
+      "removeContext": "¿Dejar de usar {{account}} como {{person}} en este dispositivo? Quien más acceda a {{account}} aquí lo conserva.",
+      "removePrincipalTitle": "¿Cerrar sesión en este dispositivo?",
+      "removePrincipal": "¿Cerrar la sesión de {{name}} en este dispositivo? Se quitan todas las cuentas a las que llega desde aquí. No afecta a nadie más."
     },
     "device": {
       "loadingTitle": "Cargando sesiones de dispositivo...",
@@ -679,6 +688,14 @@
       "openedInCommons": "Abierto en Commons",
       "confirming": "Confirmando identidad",
       "confirmed": "Identidad confirmada"
+    },
+    "context": {
+      "unavailable": "No disponible ahora mismo",
+      "operatedBy": "Gestionada por {{name}}",
+      "remove": "Quitar {{account}} de {{person}}"
+    },
+    "principal": {
+      "signOut": "Cerrar la sesión de {{name}} en este dispositivo"
     }
   },
   "feedback": {

package/dist/esm/index.js

@@ -173,16 +173,32 @@ export { SessionClient } from './session/SessionClient.js';
 export { createSessionClientHost } from './session/sessionClientHost.js';
 export { createSessionClient } from './session/createSessionClient.js';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState.js';
-// Unified account-list projection (THE single source of truth for the account
-// chooser: device sign-ins ∪ account graph, deduped by accountId). Pure +
-// I/O-free — the caller hydrates profiles via `getUsersByIds`. Shared by
-// `@oxyhq/services` and auth.oxy.so so the list can't diverge.
-// `isSwitchTargetAccount` is the structural half ("is this kind switchable at
-// all?"); `canSwitchIntoAccount` adds the caller's `account:act_as` permission.
-// Both are exported so surfaces that render `AccountNode`s rather than the
-// projection — the Console workspace switcher, managed-accounts rows — ask the
-// SAME questions instead of testing a kind literal.
-export { isSwitchTargetAccount, canSwitchIntoAccount, projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection.js';
+// Pure projections over the device DIRECTORY (`GET /session/device/directory`,
+// ADR 0002) — the read model that keeps the actor (the human who authenticated)
+// and the subject (the account being acted as) apart. The flat
+// `DeviceSessionState` collapses them into one row, so it can neither tell
+// "signed in as an org" from "a person operating that org" nor hold two people
+// reaching the same org on one device.
+// `canActivateContext` is the switchability question — `available` alone, never
+// composed with `onDevice`, which is a different fact in both directions.
+// `projectDevicePrincipals` is the switcher's shape: people, each with what
+// they may become. Grouped rather than flat because the same organization
+// reached through two people is TWO rows under two humans, which a list keyed
+// by account cannot say.
+export { canActivateContext, directoryDisplayName, directoryHandle, projectDevicePrincipals, resolveActiveContext, resolveDeviceContext, } from './session/deviceDirectory.js';
+// The switcher's RENDER model over that projection — names, handles and avatar
+// URLs resolved once. Shared by `@oxyhq/services`' account dialog and the
+// auth.oxy.so chooser so the two cannot drift, the same reason the flat
+// projection lived here before it.
+export { buildSwitcherRows, showsPrincipalHeaders } from './session/deviceSwitcherRows.js';
+// The switch-target predicates over the account GRAPH — a list of accounts to
+// manage, not the device's list of identities to become (that is the directory
+// above). `isSwitchTargetAccount` is the structural half ("is this kind
+// switchable at all?"); `canSwitchIntoAccount` adds the caller's
+// `account:act_as` permission. Exported so the surfaces that render
+// `AccountNode`s — the Console workspace switcher, managed-accounts rows — ask
+// the SAME questions instead of testing a kind literal.
+export { isSwitchTargetAccount, canSwitchIntoAccount, } from './session/accountSwitchTargets.js';
 // Headless controller for the unified account dialog. Framework-agnostic
 // state machine + subscribe/getSnapshot store (bind via `useSyncExternalStore`)
 // — sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff;
@@ -198,6 +214,12 @@ export { AccountDialogController, createAccountDialogController, } from './sessi
 // via `POST /session/device/token`.
 // ---------------------------------------------------------------------------
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore.js';
+// The shared NATIVE DeviceSession credential — how several official apps on one
+// device end up on ONE `DeviceSession` and therefore one active context. It is an
+// ordinary rotatable/revocable `deviceId` + `deviceSecret`, deliberately NOT the
+// Commons private identity key: an app that only needs a session must never be
+// handed the key that signs identity approvals.
+export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './session/sharedDeviceCredential.js';
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key
 // and the account it authenticates as; it is what keeps such a client from

package/dist/esm/mixins/OxyServices.auth.js

@@ -1140,6 +1140,23 @@ export function OxyServicesAuthMixin(Base) {
          * response this method used before were an Oxy invention no OAuth library
          * could interoperate with; the endpoint no longer accepts them. The method's
          * OWN signature is unchanged, so callers are unaffected.
+         *
+         * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
+         * outcome, not an error. A third-party grant is meant to be isolated from the
+         * browser's shared DeviceSession, so the token endpoint must be free to return
+         * no device credential at all — the guard that used to require the pair made
+         * that omission unshippable, since it turned every third-party sign-in through
+         * the SDK into a silent `exchange-failed`.
+         *
+         * The cost is real and deliberate: a DEVICE-LESS session cannot use the
+         * zero-cookie mint lane (`POST /session/device/token`), because that lane's
+         * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
+         * access token itself — nothing persists a restore credential, the cold boot's
+         * `device-secret-mint` step reports `no-secret` and skips, and the refresh
+         * scheduler has nothing to re-mint from. When the token expires the session
+         * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
+         * out, so the app can run the OAuth flow again. It never degrades into a
+         * session that looks alive and cannot refresh.
          */
         async exchangeOAuthCode(params) {
             try {
@@ -1161,7 +1178,9 @@ export function OxyServicesAuthMixin(Base) {
                 const deviceId = typeof record.deviceId === 'string' ? record.deviceId : undefined;
                 const deviceSecret = typeof record.deviceSecret === 'string' ? record.deviceSecret : undefined;
                 const userRaw = record.user;
-                if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
+                // The device pair is NOT part of this guard — see the note above. What is
+                // still mandatory is what identifies the session at all.
+                if (!sessionId || !userRaw || typeof userRaw !== 'object') {
                     throw new Error('auth/oauth/token returned an incomplete session payload');
                 }
                 const userObj = userRaw;
@@ -1174,12 +1193,17 @@ export function OxyServicesAuthMixin(Base) {
                 if (accessToken) {
                     this.setTokens(accessToken);
                 }
+                if (!deviceId || !deviceSecret) {
+                    logger.debug('auth/oauth/token returned no device credential — this session lives only as long as its access token', { component: 'oxy.auth', method: 'exchangeOAuthCode' });
+                }
                 return {
                     sessionId,
-                    deviceId,
                     expiresAt,
                     accessToken,
-                    deviceSecret,
+                    // Omitted rather than set to `undefined` when the server sent no device
+                    // credential, so a device-less grant serializes as the absence it is.
+                    ...(deviceId ? { deviceId } : {}),
+                    ...(deviceSecret ? { deviceSecret } : {}),
                     user: {
                         id: userId,
                         username: typeof userObj.username === 'string' ? userObj.username : undefined,

package/dist/esm/mixins/OxyServices.chains.js

@@ -0,0 +1,70 @@
+/**
+ * Chains — the shared record log every Oxy app reads and writes.
+ *
+ * A person has ONE chain. An app appends its own records to it and projects its
+ * feeds from what it reads back, instead of keeping a private copy of the same
+ * person's activity. This mixin is the client half of `/chains` in oxy-api, and
+ * it exists so that adopting the chain costs an app no HTTP of its own — the
+ * whole point of the shared substrate is that the second app writes less code
+ * than the first, not the same amount in a different file.
+ *
+ * ## Both calls are SERVICE-authenticated
+ *
+ * They go through `makeServiceRequest`, so they only work on a backend that has
+ * called `configureServiceAuth()`. That is not an accident of implementation: an
+ * append writes to someone else's chain and a read spans many subjects, so
+ * neither belongs in a browser holding a user session. A frontend that needs
+ * this asks its own backend.
+ *
+ * The authority is checked server-side and cannot be talked out of from here:
+ * `chains:write` plus the application's own `chainNamespaces` for an append,
+ * `chains:read` plus the public-collection policy for a read. A call that
+ * violates either gets a 403 or an empty page — this client adds no
+ * pre-validation that could drift from the server's answer.
+ */
+export function OxyServicesChainsMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Append a record to `oxyUserId`'s chain under `collection`/`rkey`.
+         *
+         * Oxy issues and signs it; the calling app never holds a chain signing key.
+         * `rkey` is the app's own id for the thing — reusing it later supersedes the
+         * earlier record for that key, which is how an edit works.
+         *
+         * Requires the `chains:write` scope AND `collection` falling under one of
+         * this application's granted `chainNamespaces`. Both are enforced by the
+         * server; a violation throws with a 403.
+         */
+        async appendChainRecord(params) {
+            return this.makeServiceRequest('POST', '/chains/records', params);
+        }
+        /**
+         * Records published by any of `oxyUserIds` under any of `collections`,
+         * oldest first — the read a cross-app feed is projected from.
+         *
+         * Only collections Oxy declares PUBLIC come back, whatever is asked for; a
+         * private one yields nothing rather than an error.
+         *
+         * **Re-poll from slightly BEFORE your last cursor and dedupe by
+         * `recordId`.** The chain's pagination axis is a transaction-start
+         * timestamp, so a record can commit behind a cursor that already passed it.
+         * Re-delivering one costs bytes; skipping one costs a record that never
+         * appears. Projections are expected to be idempotent for exactly this
+         * reason.
+         */
+        async readChainRecords(params) {
+            const query = new URLSearchParams({
+                authors: params.oxyUserIds.join(','),
+                collections: params.collections.join(','),
+            });
+            if (params.since)
+                query.set('since', params.since);
+            if (params.limit !== undefined)
+                query.set('limit', String(params.limit));
+            return this.makeServiceRequest('GET', `/chains/records?${query.toString()}`);
+        }
+    };
+}