@oxyhq/core 20.0.0 → 21.0.0

package/src/index.ts

@@ -49,7 +49,11 @@ export type {
     CommonsDeliveryPlatform,
     CommonsDeliveryRoute,
 } from './utils/commonsDelivery';
-export type { ServiceTokenResponse, OAuthUserInfoResponse } from './mixins/OxyServices.auth';
+export type {
+    ServiceTokenResponse,
+    OAuthUserInfoResponse,
+    OAuthTokenExchangeResult,
+} from './mixins/OxyServices.auth';
 // "Sign in with Oxy" — handoff (Workstream C)
 export type {
     CommonsSignInHandle,
@@ -116,6 +120,29 @@ export type {
     ConnectedApp,
 } from './mixins/OxyServices.connectedApps';
 
+// ---------------------------------------------------------------------------
+// App store (public storefront + reviews + the listing a publisher edits)
+// ---------------------------------------------------------------------------
+export type {
+    StoreCategory,
+    StoreRating,
+    StoreListingSummary,
+    StoreListingDetail,
+    StoreScreenshot,
+    StoreScreenshotPlatform,
+    StoreReview,
+    StoreOwnReview,
+    WriteStoreReviewInput,
+    StoreListingStatus,
+    PublisherListing,
+    WriteListingInput,
+    AddScreenshotInput,
+    UpdateScreenshotInput,
+    StorePage,
+    StorePageOptions,
+    StoreReviewsOptions,
+} from './mixins/OxyServices.store';
+
 // ---------------------------------------------------------------------------
 // Accounts (unified account graph: tree, membership, roles, bot credentials)
 // plus the applications owned within it (Application = OAuth client).
@@ -230,6 +257,13 @@ export type {
 } from './mixins/OxyServices.civic';
 export type { UserNodeStatus, UserNodeMode, UserNodeController, UserNodeLivenessStatus, RegisterNodeInput, RemoveNodeResult } from './mixins/OxyServices.nodes';
 
+/**
+ * Chains — the shared per-person record log. `ChainRecord` is generic over the
+ * app's own lexicon payload, so a consumer types its records without Oxy
+ * knowing any app's schema.
+ */
+export type { ChainRecord, ChainRecordPage, AppendedChainRecord } from './mixins/OxyServices.chains';
+
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------
@@ -650,26 +684,55 @@ export {
     accountIdsOf,
 } from './session/projectSessionState';
 
-// 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.
+// 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';
+export type {
+    DeviceContext,
+    DeviceContextActor,
+    DeviceContextSubject,
+    DevicePrincipalGroup,
+} from './session/deviceDirectory';
+
+// 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';
+export type {
+    ResolveAvatarUrl,
+    SwitcherContextRow,
+    SwitcherPrincipalRow,
+} from './session/deviceSwitcherRows';
+
+// 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,
-    projectSwitchableAccounts,
-    switchableAccountIds,
-} from './session/accountProjection';
-export type {
-    SwitchableAccount,
-    SwitchableAccountUser,
-    ProjectSwitchableAccountsInput,
-} from './session/accountProjection';
+} from './session/accountSwitchTargets';
 
 // Headless controller for the unified account dialog. Framework-agnostic
 // state machine + subscribe/getSnapshot store (bind via `useSyncExternalStore`)
@@ -711,6 +774,30 @@ export type {
     NativeKeyValueStorage,
 } from './session/authStateStore';
 
+// 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';
+export type {
+    SharedDeviceCredential,
+    SharedDeviceCredentialRead,
+    SharedDeviceCredentialStore,
+    SharedDeviceJoinDecision,
+    SharedDeviceJoinSkipReason,
+    SharedDevicePublishDecision,
+    SharedDevicePublishOutcome,
+    SharedDevicePublishSkipReason,
+} from './session/sharedDeviceCredential';
+
 // 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/src/mixins/OxyServices.auth.ts

@@ -7,7 +7,6 @@ import type { User } from '../models/interfaces';
 import type {
   UserNameResponse,
   LoginResult,
-  LoginSessionResult,
   CommonsDenyReason,
 } from '@oxyhq/contracts';
 import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
@@ -74,6 +73,42 @@ export interface OAuthUserInfoResponse {
   picture?: string;
 }
 
+/**
+ * The session an OAuth authorization-code exchange yields.
+ *
+ * Deliberately NOT `LoginSessionResult`. That type mirrors the API's
+ * `buildSessionAuthResponse`, which every FIRST-PARTY sign-in lane emits, and it
+ * requires `deviceId` because those lanes always join the origin's DeviceSession.
+ * `POST /auth/oauth/token` is the RFC 6749 token endpoint and serves third
+ * parties, whose grant is deliberately ISOLATED: an untrusted application must be
+ * able to receive a session carrying NO DeviceSession credential at all.
+ *
+ * Both device fields are therefore optional here, and a response omitting them is
+ * a well-formed device-less grant rather than a malformed payload. What that
+ * costs the session is spelled out on `exchangeOAuthCode` below.
+ */
+export interface OAuthTokenExchangeResult {
+  sessionId: string;
+  /** ISO-8601 expiry of {@link accessToken}, derived from RFC 6749 `expires_in`. */
+  expiresAt: string;
+  accessToken?: string;
+  /**
+   * The DeviceSession this grant joined, when the server issued one. ABSENT for
+   * an isolated third-party grant — never assume a string.
+   */
+  deviceId?: string;
+  /**
+   * The zero-cookie mint credential for {@link deviceId}. Present only alongside
+   * it; absent for an isolated third-party grant.
+   */
+  deviceSecret?: string;
+  user: {
+    id: string;
+    username?: string;
+    avatar?: string;
+  };
+}
+
 // ===========================================================================
 // "Sign in with Oxy" — cross-device QR / app-to-app handoff (Workstream C)
 // ===========================================================================
@@ -1699,13 +1734,30 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * 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: {
       code: string;
       clientId: string;
       redirectUri: string;
       codeVerifier: string;
-    }): Promise<LoginSessionResult> {
+    }): Promise<OAuthTokenExchangeResult> {
       try {
         const form = new URLSearchParams({
           grant_type: 'authorization_code',
@@ -1730,7 +1782,9 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         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 as Record<string, unknown>;
@@ -1744,12 +1798,20 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         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/src/mixins/OxyServices.chains.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/** A signed record as it comes back from a read. */
+export interface ChainRecord<TRecord = Record<string, unknown>> {
+  recordId: string;
+  /** The subject whose chain it is — the person the record is about. */
+  oxyUserId: string;
+  /** The lexicon NSID, e.g. `app.mention.feed.post`. */
+  collection: string;
+  envelope: {
+    version: number;
+    type: string;
+    subject: string;
+    issuer: string;
+    record: TRecord;
+    issuedAt: number;
+    seq?: number;
+    prev?: string | null;
+    collection?: string;
+    rkey?: string;
+    publicKey: string;
+    alg: string;
+    signature: string;
+  };
+}
+
+/** One page of a multi-subject read. */
+export interface ChainRecordPage<TRecord = Record<string, unknown>> {
+  records: ChainRecord<TRecord>[];
+  /**
+   * Opaque. Hand it back as `since` to continue; `null` at the end of the
+   * stream as of this snapshot. Never construct one.
+   */
+  nextCursor: string | null;
+}
+
+/** What an append returns once the record is on the chain. */
+export interface AppendedChainRecord {
+  recordId: string;
+  seq: number;
+  envelope: ChainRecord['envelope'];
+  verified: boolean;
+}
+
+export function OxyServicesChainsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /** Service-token request, implemented by the auth mixin earlier in the pipeline. */
+    declare makeServiceRequest: <R = unknown>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: unknown,
+      userId?: string,
+    ) => Promise<R>;
+
+    /**
+     * 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: {
+      oxyUserId: string;
+      collection: string;
+      rkey: string;
+      record: Record<string, unknown>;
+    }): Promise<AppendedChainRecord> {
+      return this.makeServiceRequest<AppendedChainRecord>('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<TRecord = Record<string, unknown>>(params: {
+      oxyUserIds: readonly string[];
+      collections: readonly string[];
+      since?: string | null;
+      limit?: number;
+    }): Promise<ChainRecordPage<TRecord>> {
+      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<ChainRecordPage<TRecord>>('GET', `/chains/records?${query.toString()}`);
+    }
+  };
+}