@oxy.so/core 1.0.0

package/dist/esm/index.js

@@ -0,0 +1,254 @@
+/**
+ * @oxy.so/core — OxyHQ SDK Foundation
+ *
+ * Platform-agnostic core providing API client, authentication,
+ * cryptographic identity, and shared utilities.
+ *
+ * Works in Node.js, Browser, and React Native.
+ *
+ * @example
+ * ```ts
+ * import { OxyServices, oxyClient } from '@oxy.so/core';
+ *
+ * const user = await oxyClient.getCurrentUser();
+ * ```
+ *
+ * Every export below is NOMINAL — no `export *`, no barrels, no compat shims.
+ * If a symbol does not appear here, it is NOT part of the public API.
+ */
+// Ensure crypto polyfills are loaded before anything else
+import './crypto/polyfill.js';
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
+export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.js';
+export { OXY_CLOUD_URL, oxyClient } from './OxyServices.js';
+// ---------------------------------------------------------------------------
+// Authentication
+// ---------------------------------------------------------------------------
+export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth.js';
+export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval.js';
+// Automatic "Sign in with Oxy" delivery selection — ONE pure decision that maps
+// the caller's facts onto exactly one primary route (open Commons / await push / QR).
+export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery.js';
+export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData.js';
+// ---------------------------------------------------------------------------
+// User identity and handles
+// ---------------------------------------------------------------------------
+export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity.js';
+export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle.js';
+export { normalizeProfileLinks } from './utils/profileLinks.js';
+export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts.js';
+// ---------------------------------------------------------------------------
+// Reputation (Oxy Trust: ledger, balances, disputes, rules, influence).
+// The whole type family — the closed value sets, the two balance views and the
+// `isFullReputationBalance` narrowing guard, the ledger/dispute/rule/leaderboard
+// shapes, and the write-endpoint inputs — is owned by `@oxy.so/contracts`, which
+// the API's serializers are validated against. Import them from there.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping,
+// verified domains). Wire shapes (DidDocument, SignedRecordEnvelope,
+// AuthMethodsResponse, VerifiedDomain, DomainVerificationInstructions,
+// ExportBundle) live in `@oxy.so/contracts` — import them directly from there.
+// ---------------------------------------------------------------------------
+export { buildUserDid } from './mixins/OxyServices.identity.js';
+// ---------------------------------------------------------------------------
+// Civic / Commons "Oxy ID" (public signed cards + Oxy ID QR payload) and Fase 2
+// anti-gaming (real-life attestation QR + validator/jury). Wire shapes
+// (PublicCard, SignedPublicCard, RealLifeAttestationResult,
+// ValidationRequestSummary, ValidationVoteResult, ValidationVerdict, …) live in
+// `@oxy.so/contracts` — import them from there. The SDK adds the client verdict
+// wrapper, the QR payload parsers/builders, and the submit inputs/results.
+// ---------------------------------------------------------------------------
+export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic.js';
+// ---------------------------------------------------------------------------
+// Auth helpers (token refresh, error normalisation, retry policies)
+// ---------------------------------------------------------------------------
+export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers.js';
+// ---------------------------------------------------------------------------
+// Sessions
+// ---------------------------------------------------------------------------
+export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils.js';
+// ---------------------------------------------------------------------------
+// Crypto / identity
+// ---------------------------------------------------------------------------
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, IdentityUnavailableError, } from './crypto/keyManager.js';
+export { readIdentityMarker, updateIdentityMarker, } from './crypto/identityMarker.js';
+export { SignatureService } from './crypto/signatureService.js';
+export { RecoveryPhraseService } from './crypto/recoveryPhrase.js';
+// Low-level crypto primitives (b3 Phase 0 — encrypted backup + device transfer)
+export { hkdfSha256 } from './crypto/kdf.js';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH, } from './crypto/aead.js';
+export { deriveSharedSecret } from './crypto/ecdh.js';
+// ---------------------------------------------------------------------------
+// Devices
+// ---------------------------------------------------------------------------
+export { DeviceManager } from './utils/deviceManager.js';
+export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces.js';
+// Topic enums + type
+export { TopicType, TopicSource } from './models/Topic.js';
+// ---------------------------------------------------------------------------
+// Languages
+// ---------------------------------------------------------------------------
+export { SUPPORTED_LANGUAGES, FALLBACK_LOCALE, getBaseLanguage, normalizeLocale, isSupportedLocale, getLanguageMetadata, getLanguageName, getNativeLanguageName, isRTLLocale, getUserLanguages, getPrimaryLanguage, } from './utils/languageUtils.js';
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+export { getPlatformOS, setPlatformOS, isWeb, isNative, isIOS, isAndroid, isWebBrowser, } from './utils/platform.js';
+// ---------------------------------------------------------------------------
+// Colour / theme utilities
+// ---------------------------------------------------------------------------
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './shared/utils/colorUtils.js';
+export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './shared/utils/themeUtils.js';
+// ---------------------------------------------------------------------------
+// HTTP / error / network helpers
+// ---------------------------------------------------------------------------
+export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './shared/utils/errorUtils.js';
+export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './shared/utils/networkUtils.js';
+// ---------------------------------------------------------------------------
+// i18n
+// ---------------------------------------------------------------------------
+export { translate } from './i18n/index.js';
+export { accountCategoryLabel } from './i18n/accountCategoryLabels.js';
+export { accountRoleLabel } from './i18n/accountRoleLabels.js';
+export { reputationCategoryLabel } from './i18n/reputationCategoryLabels.js';
+export { trustTierLabel } from './i18n/trustTierLabels.js';
+// ---------------------------------------------------------------------------
+// API request / URL helpers
+// ---------------------------------------------------------------------------
+export { buildQueryParams, buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils.js';
+export { ErrorCodes, createApiError, handleHttpError, isHttpRequestError, parseHttpErrorBody, validateRequiredFields, } from './utils/errorUtils.js';
+export { retryAsync } from './utils/asyncUtils.js';
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+export { EMAIL_REGEX, PASSWORD_REGEX, MAX_DISPLAY_NAME_LENGTH, DISPLAY_NAME_INVALID_MESSAGE, isValidEmail, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils.js';
+// ---------------------------------------------------------------------------
+// Text normalization
+// ---------------------------------------------------------------------------
+export { normalizeInlineText, normalizeMultilineText, } from './utils/textNormalization.js';
+// ---------------------------------------------------------------------------
+// Logging — the ecosystem-wide chokepoint (also at subpath `@oxy.so/core/logger`)
+// ---------------------------------------------------------------------------
+export { logger, createLogger, configureLogger, getLoggerConfig, resetLoggerConfig, consoleSink, isDev, } from './logger/index.js';
+// ---------------------------------------------------------------------------
+// Avatars
+// ---------------------------------------------------------------------------
+export { updateAvatarVisibility } from './utils/avatarUtils.js';
+// ---------------------------------------------------------------------------
+// Accounts
+// ---------------------------------------------------------------------------
+export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, getAccountColor, } from './utils/accountUtils.js';
+// ---------------------------------------------------------------------------
+// Registrable-domain + central-IdP-apex helpers.
+//
+// `registrableApex` (eTLD+1) is consumed via the `@oxy.so/core/server`
+// re-export by `packages/api/src/utils/sameSite.ts` for same-site origin
+// checks; `CENTRAL_IDP_APEX` by `server/cors.ts`'s `createOxyCors` (auto-allows
+// `*.oxy.so`).
+// ---------------------------------------------------------------------------
+export { registrableApex } from './utils/registrableApex.js';
+export { CENTRAL_IDP_APEX } from './utils/authWebUrl.js';
+// WebAuthn relying-party origin guard (client side). Mirrors the server's
+// `isOxyApexOrigin` so consumers can decide whether to offer passkey UI on the
+// current page (first-party Oxy origin / loopback only).
+export { isOxyRpOrigin } from './utils/webauthnOrigin.js';
+export { runColdBoot } from './utils/coldBoot.js';
+// ---------------------------------------------------------------------------
+// OAuth 2.0 Authorization Code + PKCE helpers ("Sign in with Oxy" third party).
+// Standard OAuth against auth.oxy.so/authorize — no FedCM/cookies/SSO bounce.
+// ---------------------------------------------------------------------------
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce.js';
+export { isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, } from './utils/officialOrigins.js';
+// ---------------------------------------------------------------------------
+// Session sync (device-scoped multi-account session client)
+// ---------------------------------------------------------------------------
+export { SessionClient } from './session/SessionClient.js';
+// Shared SessionClient integration layer: the host adapter, the pure
+// DeviceSessionState projection helpers, and the client factory are defined
+// ONCE here so every `@oxy.so/services` platform variant reuses them instead of
+// duplicating a local copy. Each consumer supplies its own `TokenTransport`
+// (native vs. web mint strategies differ) to `createSessionClient`.
+export { createSessionClientHost } from './session/sessionClientHost.js';
+export { createSessionClient } from './session/createSessionClient.js';
+export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState.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 `@oxy.so/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';
+// The service/agent counterpart to the human switch predicates above. Kept on
+// its own semantic seam because `bot` is delegable but never human-switchable.
+export { resolveAccountDelegationAccess } from './session/accountDelegationAccess.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;
+// password, social login, and 2FA were removed ecosystem-wide. Reuses
+// `SessionClient.switchAccount` / `oxyServices.switchToAccount` for the uniform
+// switch and the existing device-flow methods for sign-in.
+export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController.js';
+// ---------------------------------------------------------------------------
+// Device-first session machinery (zero-cookie transport).
+// Persisted auth-state store, the unified re-mint handler + scheduler, and the
+// cold-boot runner. Built ON the `runColdBoot` primitive + `SessionClient`. The
+// device credential is `deviceId` + `deviceSecret`; the access token is re-minted
+// 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
+// following the device's mutable `activeAccountId`.
+export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './session/identityPin.js';
+export { resolveIdentityPin, establishIdentitySession, } from './session/identitySession.js';
+// The typed `401 account_not_on_device` from a PINNED device-secret mint: the
+// pinned account left this device's session set, so the caller re-establishes
+// the identity session instead of dropping a healthy device credential.
+export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot.js';
+export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh.js';
+// The inference API. `oxyServices.inference()` binds the session bearer into
+// the same client an external developer constructs with an `oxy_sk_…` machine
+// key — one surface, two credential lanes. See `docs/inference/sdk.md`.
+export { OxyInferenceClient, OxyInferenceError, OxyInferenceProtocolError, OXY_INFERENCE_BASE_URL, } from './inference/OxyInferenceClient.js';
+export { runSessionColdBoot } from './boot/sessionColdBoot.js';
+// API response contracts (request/response Zod schemas + inferred types) live in
+// `@oxy.so/contracts` — the single source of truth shared by the backend and every
+// client SDK. Import them directly from `@oxy.so/contracts`; `@oxy.so/core` does NOT
+// re-export them (no barrel re-exports — clean imports from the owning package).
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export { packageInfo } from './constants/version.js';
+// ---------------------------------------------------------------------------
+// Default export (back-compat — OxyServices is the most common consumer entry)
+// ---------------------------------------------------------------------------
+import { OxyServices } from './OxyServices.js';
+export default OxyServices;