@oxyhq/core 3.10.1 → 3.12.0

package/dist/types/HttpService.d.ts

@@ -25,6 +25,7 @@ export interface RequestOptions {
     timeout?: number;
     signal?: AbortSignal;
     headers?: Record<string, string>;
+    responseType?: 'blob';
 }
 interface RequestConfig extends RequestOptions {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -183,6 +184,8 @@ export declare class HttpService {
      * Build full URL with query params
      */
     private buildURL;
+    private getCredentialsMode;
+    private shouldSendCredentials;
     /**
      * Fetch CSRF token from server (with deduplication)
      * Required for state-changing requests (POST, PUT, PATCH, DELETE)

package/dist/types/OxyServices.d.ts

@@ -122,7 +122,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     waitForIframeAuth(iframe: HTMLIFrameElement, timeout: number, expectedOrigin: string): Promise<SessionLoginResponse | null>;
     signInWithRedirect(options?: RedirectAuthOptions): void;
     signUpWithRedirect(options?: RedirectAuthOptions): void;
-    exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+    exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
     generateSsoState(): string;
     auth(options?: {
         debug?: boolean;
@@ -153,7 +153,7 @@ export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
 /**
  * Export the default Oxy API URL (for documentation)
  */
-export declare const OXY_API_URL: any;
+export declare const OXY_API_URL: string;
 /**
  * Pre-configured client instance for easy import
  * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL

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

@@ -0,0 +1,44 @@
+/**
+ * Canonical JSON (RFC 8785 / JCS-style) serialization.
+ *
+ * `canonicalize(value)` produces a deterministic string for any JSON-compatible
+ * value so that a client which SIGNS a record and a server which VERIFIES it
+ * agree byte-for-byte on the signing input — regardless of the order in which
+ * object keys happen to be written, how the value was deserialized, or which
+ * runtime built it.
+ *
+ * This is the load-bearing primitive for the self-sovereign identity layer's
+ * signed records (`SignatureService.signRecord` + the API's record-verify path):
+ * both sides import THIS function from `@oxyhq/core`, so cross-implementation
+ * number/string formatting differences cannot cause a verify mismatch.
+ *
+ * Rules (the JSON Canonicalization Scheme subset we need):
+ *  - Objects: keys are sorted (ascending, by UTF-16 code unit — the default
+ *    `Array.prototype.sort` order) and serialized recursively. Properties whose
+ *    value is `undefined`, a function, or a symbol are OMITTED (matching
+ *    `JSON.stringify` object semantics).
+ *  - Arrays: element order is PRESERVED; `undefined`/function/symbol elements
+ *    serialize to `null` (matching `JSON.stringify` array semantics).
+ *  - `null`, booleans, strings, and finite numbers serialize via the standard
+ *    JSON representation.
+ *  - Values exposing a `toJSON()` method (e.g. `Date`) are replaced by its
+ *    result first, then serialized — so a `Date` and its ISO-string equivalent
+ *    canonicalize identically (the wire always carries the string form).
+ *  - Non-finite numbers (`NaN`, `Infinity`) and `bigint` are not part of the
+ *    JSON data model and throw, rather than silently producing `null`.
+ *
+ * Platform-agnostic — zero dependencies, no `require()`, no react/react-native/
+ * expo. Safe in the dual CJS + ESM build.
+ */
+/**
+ * Produce the canonical JSON string for `value`.
+ *
+ * Deterministic: two structurally-equal values yield identical strings even if
+ * their object keys were written in different orders. Use this — never an
+ * ad-hoc `JSON.stringify` of a hand-sorted object — as the signing input for
+ * signed records, so client signing and server verification cannot drift.
+ *
+ * @throws if `value` (or any nested member used as the top-level/primitive)
+ *   contains a non-finite number or a `bigint`, which have no JSON form.
+ */
+export declare function canonicalize(value: unknown): string;

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

@@ -186,6 +186,13 @@ export declare class KeyManager {
      * @internal
      */
     private static _persistIdentityAtomic;
+    /**
+     * Restore the backup slot to a previously-snapshotted state. Best-effort so
+     * the original persistence error remains the one surfaced to the caller.
+     *
+     * @internal
+     */
+    private static _rollbackBackup;
     /**
      * Restore the primary slot to a previously-snapshotted (privA, pubA) pair,
      * or delete it entirely if there was no prior identity. Best-effort: every

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

@@ -4,6 +4,48 @@
  * Handles signing and verification of messages using ECDSA secp256k1.
  * Used for authenticating requests and proving identity ownership.
  */
+import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+/**
+ * The signing-input portion of a {@link SignedRecordEnvelope}: every field
+ * EXCEPT the `publicKey` and `signature`. Both the client (when signing) and
+ * the server (when verifying) canonicalize exactly these fields, so they agree
+ * on the bytes that the signature covers.
+ *
+ * The v2 chain fields (`seq`/`prev`/`collection`/`rkey`) are optional: a v1
+ * envelope omits them and is signed over only the base fields; a v2 envelope
+ * carries them and includes them in the signed bytes.
+ */
+export type SignedRecordSigningFields = Pick<SignedRecordEnvelope, 'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'> & Partial<Pick<SignedRecordEnvelope, 'seq' | 'prev' | 'collection' | 'rkey'>>;
+/**
+ * Compute the canonical signing input for a signed-record envelope.
+ *
+ * This is the single definition of "what the signature covers". `@oxyhq/core`
+ * (client signing) and `@oxyhq/api` (server verification) both call this, so a
+ * record signed by a client and verified by the server cannot drift.
+ *
+ * - **v1**: the canonical JSON of `{version, type, subject, issuer, record,
+ *   issuedAt}` — BYTE-IDENTICAL to the original scheme, so every signature
+ *   already in production keeps verifying.
+ * - **v2**: the canonical JSON additionally includes the hash-chain fields
+ *   `{seq, prev, collection, rkey}`. Because {@link canonicalize} sorts keys,
+ *   the on-the-wire field order is irrelevant; the resulting canonical key
+ *   order is `collection, issuedAt, issuer, prev, record, rkey, seq, subject,
+ *   type, version`. `prev` is `null` at genesis (serialized as `null`, not
+ *   omitted), so it is always part of the signed bytes.
+ */
+export declare function signedRecordSigningInput(fields: SignedRecordSigningFields): string;
+/**
+ * Compute the `recordId` (content address) of a signed record: the SHA-256 hex
+ * digest of its canonical {@link signedRecordSigningInput}.
+ *
+ * Deterministic and stable across runtimes (it reuses the same canonicalization
+ * + SHA-256 the signature itself is built on). The recordId is what `prev`
+ * references in the per-subject hash chain, so `@oxyhq/core` (client) and
+ * `@oxyhq/api` (server) MUST compute it identically — both call this function.
+ * It is taken over the SIGNING input (excluding `publicKey`/`signature`), so it
+ * is a pure content address of the record's meaning, independent of who signed.
+ */
+export declare function computeRecordId(fields: SignedRecordSigningFields): Promise<string>;
 export interface SignedMessage {
     message: string;
     signature: string;
@@ -63,6 +105,22 @@ export declare class SignatureService {
      * Used for challenge-response authentication
      */
     static signChallenge(challenge: string): Promise<AuthChallenge>;
+    /**
+     * Create a signed authentication challenge response using the SHARED identity
+     * key (the cross-app `group.so.oxy.shared` keychain key), not the primary
+     * device key.
+     *
+     * Mirrors {@link signChallenge} exactly — same message format
+     * (`auth:${publicKey}:${challenge}:${timestamp}`) so the server verification
+     * path is unchanged — but sources the shared public/private key from
+     * `KeyManager` and signs with `signWithKey`. Used by "Sign in with Oxy"
+     * same-device shared-keychain SSO (Mechanism A): a sibling native app proves
+     * control of the shared identity to mint its own session.
+     *
+     * Throws if no shared identity exists (native-only; the shared keychain is
+     * unavailable on web).
+     */
+    static signChallengeWithSharedKey(challenge: string): Promise<AuthChallenge>;
     /**
      * Verify a challenge response
      */
@@ -86,5 +144,59 @@ export declare class SignatureService {
         publicKey: string;
         timestamp: number;
     }>;
+    /**
+     * Build a signed-record envelope for a self-issued identity/profile record.
+     *
+     * The envelope is self-issued: `issuer` equals `subject` (the signer's DID).
+     * The signature covers the canonical JSON of every field EXCEPT `publicKey`
+     * and `signature` (see {@link signedRecordSigningInput}); `alg` is
+     * `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of the canonical bytes,
+     * DER-encoded), the same scheme this service uses everywhere else.
+     *
+     * Requires a stored identity (native secure storage); throws if none exists.
+     *
+     * @param type - The record category (`'identity'` or `'profile'`).
+     * @param subject - The subject DID the record is about (also the issuer).
+     * @param record - The arbitrary record payload to attest to.
+     */
+    static signRecord(type: SignedRecordEnvelope['type'], subject: string, record: Record<string, unknown>): Promise<SignedRecordEnvelope>;
+    /**
+     * Build a signed-record envelope (v2) carrying the per-subject hash-chain
+     * fields.
+     *
+     * Identical to {@link signRecord} (self-issued: `issuer === subject`; same
+     * `ES256K-DER-SHA256` scheme over {@link signedRecordSigningInput}) but
+     * `version` is `2` and the signed bytes additionally cover the chain fields:
+     *
+     * @param type - The record category.
+     * @param subject - The subject DID the record is about (also the issuer).
+     * @param record - The arbitrary record payload to attest to.
+     * @param chain - The hash-chain coordinates:
+     *   - `seq` — strictly-increasing sequence number for this subject's chain.
+     *   - `prev` — the `recordId` of the previous record, or `null` at genesis.
+     *   - `collection` + `rkey` — the AtProto-style record key.
+     *
+     * The caller is responsible for fetching the current chain head (so `seq` /
+     * `prev` are correct) before signing. Requires a stored identity; throws if
+     * none exists.
+     */
+    static signRecordV2(type: SignedRecordEnvelope['type'], subject: string, record: Record<string, unknown>, chain: {
+        seq: number;
+        prev: string | null;
+        collection: string;
+        rkey: string;
+    }): Promise<SignedRecordEnvelope>;
+    /**
+     * Verify a signed-record envelope: recompute the canonical signing input from
+     * the envelope's own fields and check the signature against the envelope's
+     * `publicKey`.
+     *
+     * Note: this confirms the signature is internally consistent with the
+     * embedded `publicKey`. It does NOT establish that `publicKey` is an
+     * authorized verification method for `subject` — that authorization check is
+     * the server's responsibility (it asserts the key is a current verification
+     * method on the subject's DID).
+     */
+    static verifyRecord(envelope: SignedRecordEnvelope): Promise<boolean>;
 }
 export default SignatureService;

package/dist/types/index.d.ts

@@ -30,6 +30,7 @@ export type { SilentAuthOptions } from './mixins/OxyServices.silent';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
@@ -38,9 +39,15 @@ export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle';
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
+export { normalizeProfileLinks } from './utils/profileLinks';
+export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { Application, PublicApplication, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export type { Workspace, WorkspaceMember, WorkspaceRole, WorkspaceType, WorkspaceStatus, WorkspaceMemberStatus, CreateWorkspaceInput, UpdateWorkspaceInput, InviteWorkspaceMemberInput, UpdateWorkspaceMemberInput, TransferWorkspaceOwnershipInput, WorkspaceSuccessResult, } from './mixins/OxyServices.workspaces';
 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, } from './mixins/OxyServices.identity';
+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 { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
@@ -48,8 +55,9 @@ export type { ClientSession, StorageKeys, MinimalUserData, SessionLoginResponse,
 export type { RefreshAllResponse, RefreshAllAccount, RefreshAllAccountUser, RefreshCookieResponse, } from './models/interfaces';
 export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService } from './crypto/signatureService';
-export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
+export { SignatureService, signedRecordSigningInput, computeRecordId } from './crypto/signatureService';
+export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
+export { canonicalize } from './crypto/canonicalJson';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 export { DeviceManager } from './utils/deviceManager';

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

@@ -6,6 +6,7 @@
 import type { User, RefreshAllResponse, RefreshCookieResponse } from '../models/interfaces';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
+import type { PublicApplication } from './OxyServices.applications';
 export interface ChallengeResponse {
     challenge: string;
     expiresAt: string;
@@ -48,6 +49,60 @@ export interface PublicKeyCheckResponse {
     registered: boolean;
     message: string;
 }
+/**
+ * Handle returned by {@link OxyServicesAuthMixin.startCommonsSignIn} for a
+ * relying-party app initiating a "Sign in with Oxy" flow.
+ *
+ * `sessionToken` is the SECRET, high-entropy device-flow credential — it stays
+ * on the initiating client, is exchanged once via `claimSessionByToken`, and is
+ * NEVER placed in the QR/deep-link. `authorizeCode` is the PUBLIC handle carried
+ * in `qrPayload`; the approver (Commons) resolves it via
+ * {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
+ */
+export interface CommonsSignInHandle {
+    /** Secret device-flow token (held by the initiator; exchanged via `claimSessionByToken`). */
+    sessionToken: string;
+    /** Public, single-use authorize code carried in the QR / deep-link. */
+    authorizeCode: string;
+    /** Ready-to-render deep-link / universal-link string (`oxycommons://approve?...`). */
+    qrPayload: string;
+    /** Server-authoritative expiry (epoch milliseconds). */
+    expiresAt: number;
+    /** Session lifecycle status as reported by the server (e.g. `'pending'`). */
+    status: string;
+}
+/** Poll result for a "Sign in with Oxy" device-flow session (`GET /auth/session/status`). */
+export interface CommonsSignInStatus {
+    /** True once an approver has authorized the session. */
+    authorized: boolean;
+    /** The authorized session id (present once `authorized`). */
+    sessionId?: string;
+    /** The approving identity's public key (present once `authorized`). */
+    publicKey?: string;
+    /** Lifecycle status (`'pending'` | `'authorized'` | `'cancelled'` | `'expired'`). */
+    status?: string;
+}
+/**
+ * Server-resolved approval context shown by the approver (Commons) before
+ * authorizing — the TRUSTED identity of the requesting app, resolved from the
+ * `authorizeCode` server-side (never from the QR string).
+ */
+export interface CommonsApprovalInfo {
+    /** Sanitized, display-safe identity of the requesting application. */
+    application: PublicApplication;
+    /** OAuth scopes the application is requesting. */
+    scopes: string[];
+    /** The origin the session is bound to (the RP web origin), when applicable. */
+    boundOrigin?: string;
+    /** Server-authoritative expiry (epoch milliseconds). */
+    expiresAt: number;
+    /** Session lifecycle status. */
+    status: string;
+}
+/** Result of approving / denying a "Sign in with Oxy" request. */
+export interface CommonsSignInActionResult {
+    success: boolean;
+}
 export interface ServiceTokenResponse {
     token: string;
     expiresIn: number;
@@ -275,6 +330,87 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             expiresAt: string;
             user: User;
         }>;
+        /**
+         * MECHANISM A — same-device shared-keychain SSO.
+         *
+         * Native-only. If this device holds a shared identity (the cross-app
+         * `group.so.oxy.shared` keychain key), prove control of it and mint a
+         * session: `requestChallenge(sharedPublicKey)` → `signChallengeWithSharedKey`
+         * → `verifyChallenge` (which plants the tokens). Returns `null` on web or
+         * when no shared identity is present — never throws for the absent-identity
+         * case, so a cold-boot caller can fall through to the next step.
+         *
+         * The cold-boot wiring that CALLS this lives in `OxyContext`
+         * (`@oxyhq/services`); this method just performs the exchange.
+         */
+        signInWithSharedIdentity(opts?: {
+            deviceName?: string;
+            deviceFingerprint?: string;
+        }): Promise<SessionLoginResponse | null>;
+        /**
+         * MECHANISM B (relying party) — begin a "Sign in with Oxy" handoff.
+         *
+         * Generates a secret device-flow `sessionToken` client-side (it never
+         * appears in the QR), registers it with `POST /auth/session/create`, and
+         * returns the server-issued public `authorizeCode` + ready-to-render
+         * `qrPayload`. Render the QR (web) / open the deep-link (same-device); the
+         * approver resolves the code and authorizes. Then poll with
+         * {@link pollCommonsSignIn} and, on `authorized`, exchange the
+         * `sessionToken` via the existing `claimSessionByToken`.
+         *
+         * @param params.clientId - The RP's registered OAuth client id
+         *   (ApplicationCredential publicKey); required so the server can resolve the
+         *   requesting application's identity.
+         */
+        startCommonsSignIn(params: {
+            clientId: string;
+        }): Promise<CommonsSignInHandle>;
+        /**
+         * MECHANISM B (relying party) — poll a device-flow session for approval.
+         *
+         * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
+         * caller exchanges the secret `sessionToken` via the existing
+         * `claimSessionByToken` to mint the first access token.
+         *
+         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+         */
+        pollCommonsSignIn(sessionToken: string): Promise<CommonsSignInStatus>;
+        /**
+         * MECHANISM B (approver / Commons) — resolve the TRUSTED identity of a
+         * sign-in request from its public `authorizeCode`.
+         *
+         * The returned `application` is resolved server-side and is the only safe
+         * thing to display in the approval UI — NEVER trust the app/name/origin
+         * strings carried in the QR payload. Public (no auth required).
+         *
+         * @param authorizeCode - The public code scanned from the QR / deep-link.
+         */
+        getCommonsApprovalInfo(authorizeCode: string): Promise<CommonsApprovalInfo>;
+        /**
+         * MECHANISM B (approver / Commons) — approve a sign-in request by signing a
+         * fresh challenge with the PRIMARY local identity key.
+         *
+         * Commons holds the user's identity as its primary key (not the shared
+         * key), so this uses `signChallenge`. The signed-but-cookieless authorize
+         * endpoint resolves the user from the verified signer — the RP that started
+         * the flow then claims its session. Native-only (requires a local identity).
+         *
+         * @param params.authorizeCode - The public code being approved.
+         * @param params.deviceName - Optional human-readable device label.
+         * @param params.deviceFingerprint - Optional device fingerprint.
+         */
+        approveCommonsSignIn(params: {
+            authorizeCode: string;
+            deviceName?: string;
+            deviceFingerprint?: string;
+        }): Promise<CommonsSignInActionResult>;
+        /**
+         * MECHANISM B (approver / Commons) — deny a sign-in request, cancelling the
+         * device-flow session so the RP stops waiting.
+         *
+         * @param authorizeCode - The public code being denied.
+         */
+        denyCommonsSignIn(authorizeCode: string): Promise<CommonsSignInActionResult>;
         /**
          * Refresh every device-local refresh-cookie slot in a single round trip
          * (Google-style multi-account rebuild).