@oxyhq/core 20.0.0 → 20.1.0

package/dist/types/index.d.ts

@@ -39,6 +39,7 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
+export type { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './mixins/OxyServices.store';
 export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
@@ -46,6 +47,12 @@ export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult
 export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';
 export type { CivicCardResult, IdCardRef, AttestQrPayload, ParsedAttestPayload, SubmitRealLifeAttestationInput, DenyValidationResult, VouchForPersonInput, WithdrawVouchResult, IssueCredentialInput, RevokeCredentialResult, } 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';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';

package/dist/types/mixins/OxyServices.chains.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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 declare function OxyServicesChainsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /** Service-token request, implemented by the auth mixin earlier in the pipeline. */
+        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.
+         */
+        appendChainRecord(params: {
+            oxyUserId: string;
+            collection: string;
+            rkey: string;
+            record: Record<string, unknown>;
+        }): Promise<AppendedChainRecord>;
+        /**
+         * 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.
+         */
+        readChainRecords<TRecord = Record<string, unknown>>(params: {
+            oxyUserIds: readonly string[];
+            collections: readonly string[];
+            since?: string | null;
+            limit?: number;
+        }): Promise<ChainRecordPage<TRecord>>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.store.d.ts

@@ -0,0 +1,334 @@
+/**
+ * App Store Methods Mixin
+ *
+ * The client surface for the Oxy app store: the public storefront (`/store`),
+ * the reviews people write there, and the listing a publisher edits for an
+ * application they own (`/applications/:appId/listing`).
+ *
+ * Deliberately separate from `OxyServices.accounts.ts` even though the
+ * publisher's routes hang off an application, for the same reason
+ * `OxyServices.connectedApps.ts` is: those mixins answer "may this program act
+ * for this person?", and this one answers "should this person choose it?". Turn
+ * the store off and OAuth still works — which is the test that says the store is
+ * a module over the platform rather than part of it.
+ *
+ * The two prefixes are one domain. A listing IS the store's page for an
+ * application, so both halves of its life belong to the same surface; the API
+ * puts the publisher's half beside credentials and webhooks because that is
+ * where the permission that guards it already lives, and reusing that permission
+ * is what stops a store page becoming a second, weaker way to act for somebody's
+ * app.
+ *
+ * ## What is NOT duplicated here
+ *
+ * A listing carries no name, icon or legal links: `applications` already holds
+ * them and the storefront joins them in. A rating is computed from the visible
+ * reviews on every read rather than stored, so a hidden review stops counting
+ * the moment it is hidden. Reference listings by their `slug` in the storefront
+ * (it is what every link carries) and applications by their `_id` in the
+ * publisher's calls.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/** A shelf on the storefront. */
+export interface StoreCategory {
+    /** The public identifier a link carries. Never the row id. */
+    slug: string;
+    /** What a person reads. Never derived from the slug at render time. */
+    label: string;
+    description?: string | null;
+}
+/** The rating of an app, computed from its visible reviews. */
+export interface StoreRating {
+    /** Rounded to one decimal, or `null` when nobody has reviewed it — never 0. */
+    average: number | null;
+    count: number;
+}
+/** An app as a card on the storefront: what a listing page needs, and no more. */
+export interface StoreListingSummary {
+    slug: string;
+    /** From the APPLICATION, joined in — the listing keeps no copy. */
+    name: string;
+    tagline: string | null;
+    /** A file id for the app's icon, resolved through the usual image resolver. */
+    icon: string | null;
+    category: StoreCategory | null;
+    rating: StoreRating;
+}
+/** A store page in full. */
+export interface StoreListingDetail extends StoreListingSummary {
+    description: string | null;
+    /** These four come from the application; the consent screen shows the same values. */
+    websiteUrl: string | null;
+    privacyPolicyUrl: string | null;
+    termsUrl: string | null;
+    supportUrl: string | null;
+    supportEmail: string | null;
+    publishedAt: string | null;
+    screenshots: StoreScreenshot[];
+    /** How many visible reviews gave each of 1..5. Absent keys are zero. */
+    ratingBreakdown: Record<number, number>;
+}
+/** Which frame a screenshot was taken in. The store groups by it on the page. */
+export type StoreScreenshotPlatform = 'phone' | 'tablet' | 'desktop' | 'web';
+export interface StoreScreenshot {
+    id: string;
+    /** The uploaded asset's file id. Upload through the assets surface first. */
+    fileId: string;
+    platform: StoreScreenshotPlatform;
+    caption: string | null;
+    position: number;
+}
+/** Somebody's review, as it appears on a store page. */
+export interface StoreReview {
+    id: string;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    createdAt: string;
+    author: {
+        id: string;
+        username: string | null;
+    };
+    /** The publisher's answer, when there is one. */
+    reply: {
+        body: string;
+        createdAt: string;
+    } | null;
+    /**
+     * Whether this author has authorized the application, read from their grant
+     * at request time rather than stored on the review.
+     *
+     * It is not a claim that they still use it, and it is `false` for a
+     * first-party app nobody has to consent to — so render its absence as nothing
+     * at all rather than as a demotion.
+     */
+    authorUsesApp: boolean;
+}
+/** A review as its own author sees it, whatever its moderation state. */
+export interface StoreOwnReview {
+    id: string;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    /** An author is told when their review is hidden; the public list is not. */
+    status: 'visible' | 'hidden' | 'flagged' | 'removed';
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a person submits about an app. One review each; writing again replaces it. */
+export interface WriteStoreReviewInput {
+    /** Whole stars, 1 to 5. The database enforces the bound too. */
+    rating: number;
+    title?: string | null;
+    body?: string | null;
+}
+/** Where a listing is in its life. `pending_review` is the STORE's review of the page. */
+export type StoreListingStatus = 'draft' | 'pending_review' | 'published' | 'rejected';
+/** A listing as its publisher sees it: whatever state it is in. */
+export interface PublisherListing {
+    id: string;
+    applicationId: string;
+    slug: string;
+    tagline: string | null;
+    description: string | null;
+    category: StoreCategory | null;
+    supportUrl: string | null;
+    supportEmail: string | null;
+    status: StoreListingStatus;
+    publishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * The whole page, not a patch: sending everything is what makes "clear the
+ * tagline" expressible at all.
+ *
+ * `status` is absent on purpose. Publishing is the store's decision and has its
+ * own calls, so a publisher cannot publish themselves by putting a field in a
+ * body.
+ */
+export interface WriteListingInput {
+    /** Lowercase letters, digits and single hyphens. What every link carries. */
+    slug: string;
+    tagline?: string | null;
+    description?: string | null;
+    /** A category SLUG, never its id. */
+    categorySlug?: string | null;
+    supportUrl?: string | null;
+    supportEmail?: string | null;
+}
+export interface AddScreenshotInput {
+    /** An already-uploaded image. Must be live, an image, and yours to publish. */
+    fileId: string;
+    platform?: StoreScreenshotPlatform;
+    caption?: string | null;
+}
+export interface UpdateScreenshotInput {
+    platform?: StoreScreenshotPlatform;
+    caption?: string | null;
+}
+/**
+ * One page of a paginated store read.
+ *
+ * `hasMore` comes from the API rather than being derived here, so a caller that
+ * pages does not have to re-implement the boundary the server already computed.
+ */
+export interface StorePage<T> {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+}
+/** Options for paging the storefront and the reviews under an app. */
+export interface StorePageOptions {
+    limit?: number;
+    offset?: number;
+}
+export interface StoreReviewsOptions extends StorePageOptions {
+    /** Newest first by default; `rating` surfaces the strongest opinions. */
+    sort?: 'recent' | 'rating';
+}
+export declare function OxyServicesStoreMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /** The shelves, in the order the store curates them. */
+        listStoreCategories(): Promise<StoreCategory[]>;
+        /**
+         * Published listings, newest first, optionally one shelf.
+         *
+         * An unknown category slug is an EMPTY shelf, not every app on the store —
+         * so a typo shows nothing rather than showing everything.
+         *
+         * @param options - `category` is a category slug; `limit` defaults to 24.
+         */
+        listStoreApps(options?: StorePageOptions & {
+            category?: string;
+        }): Promise<StorePage<StoreListingSummary>>;
+        /**
+         * One store page.
+         *
+         * A draft answers 404 exactly as an unknown slug does: whether an
+         * unpublished page exists under a name is not something a visitor learns.
+         *
+         * @param slug - The listing's public slug, not an application id.
+         */
+        getStoreApp(slug: string): Promise<StoreListingDetail>;
+        /** Visible reviews for a published app, each with the publisher's reply. */
+        listStoreReviews(slug: string, options?: StoreReviewsOptions): Promise<StorePage<StoreReview>>;
+        /** The caller's own review of an app, or `null` if they have not written one. */
+        getMyStoreReview(slug: string): Promise<StoreOwnReview | null>;
+        /**
+         * Write the caller's review, or replace what they said before.
+         *
+         * A person has one review per app, so this sets it rather than adding one.
+         * Rewriting does not clear a moderator's decision: a hidden review stays
+         * hidden when its author edits it.
+         */
+        writeStoreReview(slug: string, input: WriteStoreReviewInput): Promise<StoreOwnReview>;
+        /** Withdraw the caller's own review. A real delete — the words were theirs. */
+        deleteMyStoreReview(slug: string): Promise<void>;
+        /**
+         * Answer a review on the publisher's behalf.
+         *
+         * Requires `app:update` over the application's owning account — the same
+         * permission that guards every other write to that application. Addressed
+         * by review id because the reply belongs to the review, and a listing can be
+         * renamed or withdrawn out from under it.
+         */
+        replyToStoreReview(reviewId: string, body: string): Promise<{
+            id: string;
+            reviewId: string;
+            body: string;
+        }>;
+        /** Withdraw the publisher's answer. Same permission that wrote it. */
+        deleteStoreReviewReply(reviewId: string): Promise<void>;
+        /** The application's store page in whatever state, or `null` if it has none. */
+        getAppListing(applicationId: string): Promise<PublisherListing | null>;
+        /**
+         * Create the page or replace its content. Never its status.
+         *
+         * Editing does not move a page: correcting a typo on a live listing leaves
+         * it live, and fixing a rejected one does not re-submit it.
+         */
+        writeAppListing(applicationId: string, input: WriteListingInput): Promise<PublisherListing>;
+        /** Hand the page to the store for review. From a draft, or a rejected page once fixed. */
+        submitAppListing(applicationId: string): Promise<PublisherListing>;
+        /**
+         * Take the page down, or withdraw it from the queue.
+         *
+         * Back to a draft, never deleted: the slug, the words and the screenshots
+         * are the publisher's work, and the reviews were never the listing's to take
+         * with them.
+         */
+        unpublishAppListing(applicationId: string): Promise<PublisherListing>;
+        /** Every picture on the listing, in the author's order. */
+        listAppListingScreenshots(applicationId: string): Promise<StoreScreenshot[]>;
+        /**
+         * Attach an already-uploaded image, appended to the end.
+         *
+         * Upload through the assets surface first; the store keeps a reference
+         * rather than a second copy of the asset pipeline. The file must be live, an
+         * image, and one the caller is entitled to.
+         */
+        addAppListingScreenshot(applicationId: string, input: AddScreenshotInput): Promise<StoreScreenshot>;
+        /** Edit a picture's caption or the frame it was taken in. Order is {@link reorderAppListingScreenshots}. */
+        updateAppListingScreenshot(applicationId: string, screenshotId: string, input: UpdateScreenshotInput): Promise<StoreScreenshot>;
+        /** Remove a picture. The uploaded file stays — it may be in use elsewhere. */
+        deleteAppListingScreenshot(applicationId: string, screenshotId: string): Promise<void>;
+        /**
+         * Set the order of every picture at once.
+         *
+         * Send EVERY id on the listing, exactly once, in the order they should
+         * appear. A partial list is rejected rather than applied: it would leave the
+         * pictures it omits at their old positions, interleaved with the new ones.
+         */
+        reorderAppListingScreenshots(applicationId: string, screenshotIds: string[]): Promise<StoreScreenshot[]>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -109,18 +109,41 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Uses server-side session validation for security (not just JWT decode).
          *
          * **Design note — jwtDecode vs jwt.verify:**
-         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
-         * verification) for user tokens. This is by design, NOT a security gap:
-         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
-         * - Security comes from API-based session validation (`validateSession()`)
-         *   which checks the session server-side on every request
-         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
-         *   via the `jwtSecret` option, since they are stateless. Service tokens
-         *   are additionally checked for `aud`, `iss`, and `type` claims to prevent
+         * This middleware uses `jwtDecode()` (decode-only, NO signature check) for
+         * user tokens, because third-party apps mounting `oxy.auth()` do not hold
+         * the Oxy signing secret. **Every claim in a user token is therefore
+         * attacker-controlled and proves nothing on its own.** The identity comes
+         * from somewhere else entirely:
+         * - A user token MUST carry a `sessionId`. That session is validated
+         *   server-side on every request via `validateSession()`, and the user id
+         *   is read off the VALIDATED SESSION — never off the token. A token whose
+         *   `userId` claim disagrees with the session is refused
+         *   (`SESSION_USER_MISMATCH`); a token with no `sessionId` at all is
+         *   refused outright (`SESSION_REQUIRED`). There is no local-claims path.
+         * - Service tokens (type: 'service') ARE stateless, so they use
+         *   cryptographic HMAC verification via the `jwtSecret` option, and are
+         *   additionally checked for `aud`, `iss`, and `type` claims to prevent
          *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
          *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
          *
+         * **Why session-less user tokens are refused rather than trusted:**
+         * every user access token the Oxy API issues carries a `sessionId` (see
+         * `packages/api/src/utils/sessionUtils.ts`, `generateSessionTokens` — the
+         * only mint site for user tokens, including the OAuth code exchange). So
+         * refusing session-less user tokens costs nothing legitimate, while
+         * accepting them let anyone authenticate as anyone by hand-rolling a JWT
+         * with a `userId` claim and a garbage signature.
+         *
+         * **Why the claimed user id is cross-checked against the session:**
+         * `GET /session/validate/:sessionId` is UNAUTHENTICATED and does not bind
+         * the bearer token — it returns whoever owns the session id it was handed.
+         * Trusting the token's `userId` claim after a successful validation would
+         * therefore let a caller holding ANY live session id (their own, for
+         * instance) pair it with a forged `userId` and be trusted as that user.
+         * `authSocket()` has always cross-checked this; the HTTP middleware now
+         * does too.
+         *
          * **Service-token delegation (X-Oxy-User-Id):**
          * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
          * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation

package/dist/types/mixins/index.d.ts

@@ -16,6 +16,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesStoreMixin } from './OxyServices.store';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
 import { OxyServicesDevicesMixin } from './OxyServices.devices';
@@ -27,6 +28,7 @@ import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesNotificationsMixin } from './OxyServices.notifications';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
@@ -41,7 +43,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "20.0.0",
+  "version": "20.1.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -116,6 +116,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 +253,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)
 // ---------------------------------------------------------------------------