@oxyhq/core 14.0.0 → 15.0.0

package/dist/types/crypto/recoveryPhrase.d.ts

@@ -5,6 +5,12 @@
  * for backing up and restoring user identities.
  *
  * Note: This module requires the polyfill to be loaded first (done via crypto/index.ts)
+ *
+ * Oxy recovery phrases are English-only, so the English wordlist is imported by
+ * its own subpath. Never reach for a package that exposes its wordlists through
+ * a barrel: `bip39`'s `_wordlists` hard-requires all ten languages, which put
+ * ~265 KB of unreachable wordlists into the initial chunk of every consuming
+ * app. Adding another language means one more subpath import, ideally lazy.
  */
 /**
  * HKDF context tag for the encrypted-backup key schedule (b3 Feature 1). Used as

package/dist/types/index.d.ts

@@ -41,7 +41,6 @@ export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
 export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, 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 { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
-export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
 export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';

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

@@ -12,8 +12,13 @@
  * This method carries NO persistence or token-planting side effects of its own;
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
+ *
+ * `provisionBackgroundCredential` is the mixin's second, adjacent call: it hands
+ * native background code (no JS runtime) its own non-rotating credential so that
+ * code never has to mint from — and therefore never rotates — the device secret
+ * JS depends on.
  */
-import { type DeviceTokenMintResponse } from '@oxyhq/contracts';
+import { type DeviceBackgroundCredentialResponse, type DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
@@ -71,6 +76,43 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
         mintFromDeviceSecret(deviceId: string, deviceSecret: string, options?: {
             accountId?: string;
         }): Promise<DeviceTokenMintResponse>;
+        /**
+         * Provision a NON-rotating background credential for the caller's account on
+         * this device — the credential native background code (an Android widget
+         * worker, which runs with no JS runtime) presents to mint its own access
+         * tokens without any JS involvement.
+         *
+         * It exists precisely so background code never touches the device secret:
+         * `POST /session/device/token` ROTATES that secret on every mint (the
+         * presented one stays valid only for a short grace), so a worker minting
+         * from it would become a second writer of the value JS depends on and could
+         * silently sign the user out. The background credential is a separate,
+         * non-rotating value minted server-side, so the two lanes never contend.
+         *
+         * Bearer required and NO body: the server derives both the `deviceId` and
+         * the account from the validated bearer. This is the only way a background
+         * credential comes into existence, so background code can EXTEND a session
+         * the user established in-app but can never bootstrap one from nothing.
+         *
+         * Unlike the mint above this is NOT a control-plane call — it runs while a
+         * session is already live — so it takes the normal authenticated path: no
+         * `skipAuth` (a 401 should go through the ordinary re-mint lane) and no
+         * `bypassQueue` (nothing in the auth lane is parked awaiting it).
+         *
+         * There is deliberately no JS counterpart that MINTS from the returned
+         * credential: the native side owns that call, and a symmetric-looking JS
+         * method would be dead code plus a second implementation of the failure
+         * rules. The asymmetry is the design.
+         *
+         * @returns the provisioned credential, or `null` when the endpoint is absent
+         * (404). The API deploy leads the SDK release, so a client on a newer SDK
+         * than the server degrades to "no background session" quietly instead of
+         * surfacing an error. The status is read off the RAW rejection because
+         * `handleError` only preserves it for errors carrying `HttpService`'s
+         * annotations.
+         * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
+         */
+        provisionBackgroundCredential(): Promise<DeviceBackgroundCredentialResponse | null>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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

@@ -7,7 +7,7 @@
  *
  * Key schedule (from the recovery phrase; see
  * {@link RecoveryPhraseService.deriveBackupMaterial}):
- *   seed      = bip39.mnemonicToSeed(phrase)                    // 64 bytes, UNCHANGED
+ *   seed      = mnemonicToSeed(phrase)                          // 64 bytes, UNCHANGED
  *   backupKey = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-encryption-key')
  *   lookupId  = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-lookup-id')   // hex
  *

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

@@ -12,291 +12,54 @@
  * their `active` transactions, augmented with a trust tier, capped influence
  * weights, and reliability signals.
  *
+ * A balance is served in TWO views (see `ReputationBalanceView`): the subject
+ * and platform staff get the whole thing, a third party gets the public trust
+ * signal only. The two are distinct types so a caller cannot read a field the
+ * server did not send them.
+ *
+ * EVERY type on this surface is owned by `@oxyhq/contracts`, which the API's
+ * serializers are annotated and validated against. This mixin declares none of
+ * them and re-exports none of them: consumers import the types straight from
+ * `@oxyhq/contracts`, so the wire shape has exactly one definition and a
+ * server-side change to a serializer cannot compile while the type still
+ * promises the old shape.
+ *
  * Reference users by their Mongo `_id` (or publicKey, which the API resolves),
  * transactions by their `id`, and disputes by their `id`.
  */
+import type { AwardReputationInput, CreateReputationDisputeInput, ReputationBalance, ReputationBalanceView, ReputationDispute, ReputationInfluenceContext, ReputationInfluenceResult, ReputationLeaderboardEntry, ReputationRule, ReputationTransaction, ResolveReputationDisputeInput, ReverseReputationTransactionInput, ReverseReputationTransactionResult, UpsertReputationRuleInput } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
-import type { User } from '../models/interfaces';
-/**
- * Category bucket a reputation transaction falls into. Drives the per-category
- * balance breakdown.
- */
-export type ReputationCategory = 'content' | 'social' | 'trust' | 'moderation' | 'physical' | 'penalty' | 'other';
-/** Trust tiers, lowest → highest (plus the punitive `restricted`). */
-export type TrustTier = 'new' | 'trusted' | 'high_trust' | 'verified' | 'restricted';
-/**
- * Transaction lifecycle status. Only `active` transactions count toward the
- * balance; `disputed` still counts until the dispute resolves; `reversed` and
- * `voided` are excluded.
- */
-export type ReputationTransactionStatus = 'active' | 'disputed' | 'reversed' | 'voided';
-/** Kind of entity a transaction may target. */
-export type ReputationTargetEntityType = 'post' | 'comment' | 'report' | 'purchase' | 'event' | 'check_in' | 'manual_review' | 'user' | 'other';
-/** Dispute lifecycle status. */
-export type ReputationDisputeStatus = 'open' | 'accepted' | 'rejected' | 'needs_review';
-/** Influence context selecting which capped weight axis to return. */
-export type ReputationInfluenceContext = 'default' | 'report' | 'moderation' | 'ranking';
-/**
- * A single immutable entry in the reputation ledger. Ids are emitted as strings
- * and dates as ISO strings by the API.
- */
-export interface ReputationTransaction {
-    /** The transaction's Mongo `_id` as a string. */
-    id: string;
-    /** Subject of the reputation change — the user whose balance moves. */
-    userId: string;
-    /** Signed point delta. Positive awards, negative penalties/reversals. */
-    points: number;
-    /** The rule/action key that produced this transaction (e.g. `post_created`). */
-    actionType: string;
-    /** Category bucket the points fall into. */
-    category: ReputationCategory;
-    /** Canonical source application that reported the action, if any. */
-    applicationId?: string;
-    /** The specific credential used by the source application, if any. */
-    credentialId?: string;
-    /** Opaque id of the originating action in the source system (idempotency key). */
-    sourceActionId?: string;
-    /** Source-system action type (e.g. `report_confirmed`, `event_check_in`). */
-    sourceActionType?: string;
-    /** Id of the entity the action targeted (post id, report id, etc.). */
-    targetEntityId?: string;
-    /** Kind of the targeted entity. */
-    targetEntityType?: ReputationTargetEntityType;
-    /** Lifecycle status — only `active` transactions count toward the balance. */
-    status: ReputationTransactionStatus;
-    /**
-     * Set ONLY on a compensating reversal transaction; references the original
-     * transaction it reverses. The original carries `status: 'reversed'`.
-     */
-    reversedTransactionId?: string;
-    /** Human-readable reason / note. */
-    reason?: string;
-    /** Free-form structured metadata from the source system. */
-    metadata?: Record<string, unknown>;
-    /** The user who caused this change (the liker, the reporting user, staff). */
-    createdByUserId?: string;
-    /** Staff/service principal who reviewed (reversed/voided) this transaction. */
-    reviewedByUserId?: string;
-    /** ISO timestamp the transaction was reviewed at, if reviewed. */
-    reviewedAt?: string;
-    /** ISO creation timestamp. */
-    createdAt: string;
-    /** ISO last-update timestamp. */
-    updatedAt: string;
-}
-/**
- * Per-category sums of a user's ACTIVE transactions. `penalties` is the
- * absolute sum of every negative-point transaction; the named buckets carry the
- * signed sum of transactions in that category.
- */
-export interface ReputationBalanceBreakdown {
-    content: number;
-    social: number;
-    trust: number;
-    moderation: number;
-    physical: number;
-    penalties: number;
-}
-/**
- * Capped influence weights (#219). Every weight is clamped to a configured
- * range; restricted users are floored on every axis. Downstream systems
- * (ranking, moderation, reporting) consume these to weight a user's
- * contributions without letting any single user dominate.
- */
-export interface ReputationInfluence {
-    /** General-purpose trust weight derived from the lifetime total. */
-    defaultWeight: number;
-    /** Weight applied to this user's reports (scales with report accuracy). */
-    reportWeight: number;
-    /** Weight applied to this user's moderation actions (scales with tier). */
-    moderationWeight: number;
-    /** Damped weight applied to this user's ranking feedback. */
-    rankingFeedbackWeight: number;
-}
-/**
- * Reliability signals (#219) derived from the user's moderation track record in
- * the ledger.
- */
-export interface ReputationReliability {
-    /** Count of active transactions stamped `report_confirmed`. */
-    accurateReports: number;
-    /** Count of active transactions stamped `report_rejected`. */
-    rejectedReports: number;
-    /** accurate / (accurate + rejected), or the neutral 0.5 when no history. */
-    reportAccuracyScore: number;
-    /** Smoothed 0..1 abuse signal; high values force the `restricted` tier. */
-    abuseScore: number;
-}
-/**
- * Cached, recomputable snapshot of a user's reputation. Shape mirrors the
- * `/reputation/:userId/balance` response (which omits internal `lastTransactionId`
- * and `createdAt`).
- */
-export interface ReputationBalance {
-    userId: string;
-    /** Net lifetime total across all active transactions. */
-    total: number;
-    /** Sum of positive points only. */
-    positive: number;
-    /** Sum of negative points only (a negative number). */
-    negative: number;
-    breakdown: ReputationBalanceBreakdown;
-    trustTier: TrustTier;
-    influence: ReputationInfluence;
-    reliability: ReputationReliability;
-    /** ISO timestamp the snapshot was last recomputed at. */
-    recalculatedAt: string;
-    /** ISO last-update timestamp. */
-    updatedAt: string;
-}
-/**
- * A user-initiated dispute against a specific reputation transaction. Ids are
- * strings and dates ISO strings.
- */
-export interface ReputationDispute {
-    /** The dispute's Mongo `_id` as a string. */
-    id: string;
-    /** The transaction being disputed. */
-    transactionId: string;
-    /** The user raising the dispute. */
-    userId: string;
-    /** Why the user believes the transaction is wrong. */
-    reason: string;
-    status: ReputationDisputeStatus;
-    /** Optional supporting evidence (URLs / references). */
-    evidence?: string[];
-    /** ISO timestamp the dispute was resolved at, if resolved. */
-    resolvedAt?: string;
-    /** Staff principal who resolved the dispute, if resolved. */
-    resolvedByUserId?: string;
-    /** ISO creation timestamp. */
-    createdAt: string;
-    /** ISO last-update timestamp. */
-    updatedAt: string;
-}
-/**
- * A configurable reputation award/penalty rule. The `/reputation/rules`
- * response shape: `id` is the rule's `_id`; no timestamps are emitted.
- */
-export interface ReputationRule {
-    /** The rule's Mongo `_id` as a string. */
-    id: string;
-    /** Unique action key (e.g. `post_created`). */
-    actionType: string;
-    /** Signed points the rule awards (may be negative for penalties). */
-    points: number;
-    /** Category the resulting transaction is filed under. */
-    category: ReputationCategory;
-    description: string;
-    /** Per (user, actionType) cooldown in minutes; 0 disables the cooldown. */
-    cooldownInMinutes: number;
-    isEnabled: boolean;
-}
-/**
- * A single leaderboard entry. `user` is the populated user document the API
- * returns alongside the lifetime total, derived trust tier, and 1-based rank.
- */
-export interface ReputationLeaderboardEntry {
-    /** The populated user (id, username, name, avatar, publicKey). */
-    user: Pick<User, 'id' | 'username' | 'name' | 'avatar' | 'publicKey'> & Partial<User>;
-    /** Net lifetime total. */
-    total: number;
-    /** Derived trust tier. */
-    trustTier: TrustTier;
-    /** 1-based rank within the leaderboard (`offset + index + 1`). */
-    rank: number;
-}
-/**
- * Result of `getReputationInfluence` — the requested context, the single capped
- * weight for that context, and the full influence block.
- */
-export interface ReputationInfluenceResult {
-    context: ReputationInfluenceContext;
-    weight: number;
-    influence: ReputationInfluence;
-}
-/**
- * Result of `reverseReputationTransaction` — the now-`reversed` original plus
- * the compensating `active` reversal entry.
- */
-export interface ReverseReputationTransactionResult {
-    original: ReputationTransaction;
-    reversal: ReputationTransaction;
-}
-/**
- * Input for `awardReputation`. Awarding is restricted to service tokens (the
- * canonical path) and platform staff; regular users may NOT award reputation.
- * When called with a service token, `applicationId` / `credentialId` are
- * resolved from the token and any client-supplied values are ignored.
- */
-export interface AwardReputationInput {
-    /** The subject whose reputation changes (`_id` or publicKey). */
-    userId: string;
-    /** The enabled rule's action key (e.g. `post_created`). */
-    actionType: string;
-    /** Source application id (ignored for service tokens). */
-    applicationId?: string;
-    /** Source credential id (ignored for service tokens). */
-    credentialId?: string;
-    /** Opaque originating-action id used as the idempotency key. */
-    sourceActionId?: string;
-    /** Source-system action type. */
-    sourceActionType?: string;
-    /** Id of the targeted entity. */
-    targetEntityId?: string;
-    /** Kind of the targeted entity. */
-    targetEntityType?: ReputationTargetEntityType;
-    /** Optional human-readable reason (max 500 chars). */
-    reason?: string;
-    /** Free-form structured metadata from the source system. */
-    metadata?: Record<string, unknown>;
-}
-/** Input for `createReputationDispute`. The disputer is the authenticated user. */
-export interface CreateReputationDisputeInput {
-    /** The transaction being disputed. */
-    transactionId: string;
-    /** Why the transaction is believed to be wrong (1..1000 chars). */
-    reason: string;
-    /** Optional supporting evidence (URLs / references; max 20). */
-    evidence?: string[];
-}
-/** Input for `resolveReputationDispute` (staff). */
-export interface ResolveReputationDisputeInput {
-    /** Accepting reverses the disputed transaction; rejecting restores it. */
-    status: 'accepted' | 'rejected';
-}
-/** Input for `upsertReputationRule` (staff). Keyed by `actionType`. */
-export interface UpsertReputationRuleInput {
-    /** Unique action key (e.g. `post_created`). */
-    actionType: string;
-    /** Signed points the rule awards (may be negative). */
-    points: number;
-    /** Category the resulting transaction is filed under. */
-    category: ReputationCategory;
-    /** Human-readable description (1..500 chars). */
-    description: string;
-    /** Per (user, actionType) cooldown in minutes; defaults to 0. */
-    cooldownInMinutes?: number;
-    /** Whether the rule is active; defaults to true. */
-    isEnabled?: boolean;
-}
-/**
- * Input for `reverseReputationTransaction` / `voidReputationTransaction`
- * (staff). The reviewing principal is the authenticated user.
- */
-export interface ReverseReputationTransactionInput {
-    /** Optional human-readable reason (max 500 chars). */
-    reason?: string;
-}
 export declare function OxyServicesReputationMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
-         * Get a user's cached reputation balance — derived totals, per-category
-         * breakdown, trust tier, capped influence weights, and reliability signals.
+         * Get ANY user's reputation balance, in whichever view the server serves the
+         * caller.
+         *
+         * A third party gets `userId`, `total` and `trustTier` and nothing else, so
+         * the return type is a {@link ReputationBalanceView} union: narrow it with
+         * {@link isFullReputationBalance} before touching `breakdown`, `influence`
+         * or `reliability`. To read your OWN balance, call
+         * {@link getMyReputationBalance} instead — it returns the full shape with no
+         * narrowing.
+         *
          * @param userId - The subject user's `_id` or publicKey.
          */
-        getReputationBalance(userId: string): Promise<ReputationBalance>;
+        getReputationBalance(userId: string): Promise<ReputationBalanceView>;
+        /**
+         * Get the SIGNED-IN user's own reputation balance, in full.
+         *
+         * The subject view is the only one carrying `breakdown`, `influence` and
+         * `reliability`, and the subject is the common caller, so this is the
+         * ergonomic path: no id to pass, no narrowing to do.
+         *
+         * Throws rather than returning a half-populated object when the request was
+         * not authenticated as the subject — with no signed-in user, and when the
+         * server answered `200` with the public view anyway (which it does for an
+         * absent or lapsed token, since the endpoint's auth is optional). Both mean
+         * the private blocks are simply absent, and a thrown error is the only
+         * honest report of that.
+         */
+        getMyReputationBalance(): Promise<ReputationBalance>;
         /**
          * Get the reputation leaderboard, ordered by lifetime total descending.
          * @param limit - Page size (server-capped).
@@ -365,6 +128,10 @@ export declare function OxyServicesReputationMixin<T extends typeof OxyServicesB
         /**
          * Force a recompute of a user's balance snapshot from their active ledger
          * (staff only). Invalidates cached reputation reads.
+         *
+         * Staff-gated, so the response is always the full subject view — no
+         * narrowing needed.
+         *
          * @param userId - The subject user's `_id` or publicKey.
          */
         recalculateReputation(userId: string): Promise<ReputationBalance>;

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

@@ -182,7 +182,10 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         /**
          * Get profiles similar to a given user, based on co-follower overlap.
          */
-        getSimilarProfiles(userId: string, limit?: number): Promise<User[]>;
+        getSimilarProfiles(userId: string, limitOrParams?: number | {
+            limit?: number;
+            offset?: number;
+        }): Promise<User[]>;
         /**
          * Get user by ID.
          *

package/dist/types/models/interfaces.d.ts

@@ -215,6 +215,9 @@ export interface BlockedUser {
         _id: string;
         username: string;
         avatar?: string;
+        name?: {
+            displayName?: string;
+        };
     };
     userId: string;
     createdAt?: string;
@@ -228,6 +231,9 @@ export interface RestrictedUser {
         _id: string;
         username: string;
         avatar?: string;
+        name?: {
+            displayName?: string;
+        };
     };
     userId: string;
     createdAt?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "14.0.0",
+  "version": "15.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,9 +115,9 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.19.0",
+    "@oxyhq/contracts": "^0.20.0",
     "@oxyhq/protocol": "^0.1.6",
-    "bip39": "^3.1.0",
+    "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
     "invariant": "^2.2.4",

package/src/crypto/__tests__/keyManager.test.ts

@@ -309,8 +309,9 @@ describe('KeyManager safety invariants', () => {
       (KeyManager as unknown as { cachedPublicKey: unknown; cachedHasIdentity: unknown }).cachedHasIdentity = null;
 
       // Manually generate a different phrase
-      const bip39 = await import('bip39');
-      const otherPhrase = bip39.generateMnemonic(128);
+      const { generateMnemonic } = await import('@scure/bip39');
+      const { wordlist } = await import('@scure/bip39/wordlists/english');
+      const otherPhrase = generateMnemonic(wordlist, 128);
       // Sanity check phrases are different
       expect(otherPhrase).not.toBe(a.phrase);