@oxyhq/core 4.0.1 → 5.0.0

package/src/crypto/signatureService.ts

@@ -1,108 +1,26 @@
 /**
- * Signature Service - ECDSA Digital Signatures
- * 
- * Handles signing and verification of messages using ECDSA secp256k1.
- * Used for authenticating requests and proving identity ownership.
+ * Signature Service - ECDSA Digital Signatures (device-key bound)
+ *
+ * Handles signing and verification of messages with the user's DEVICE identity
+ * key (read from {@link KeyManager} / secure storage). All cryptography itself —
+ * canonical signing input, SHA-256, secp256k1 sign/verify, envelope assembly —
+ * is delegated to `@oxyhq/protocol`; this service only resolves the key from
+ * storage and orchestrates the protocol primitives.
  */
 
-import { ec as EC } from 'elliptic';
 import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+import {
+  signEnvelope,
+  signMessage,
+  verifySignature,
+  sha256,
+  loadExpoCrypto,
+  loadNodeCrypto,
+  isReactNative,
+  isNodeJS,
+} from '@oxyhq/protocol';
 import { KeyManager } from './keyManager';
-import { canonicalize } from './canonicalJson';
-import { isReactNative, isNodeJS } from '../utils/platform';
-import { loadExpoCrypto, loadNodeCrypto } from '../utils/platformCrypto';
 import { logger } from '../utils/loggerUtils';
-import { isDev } from '../shared/utils/debugUtils';
-
-const ec = new EC('secp256k1');
-
-/**
- * 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 function signedRecordSigningInput(fields: SignedRecordSigningFields): string {
-  const { version, type, subject, issuer, record, issuedAt } = fields;
-  if (version === 2) {
-    const { seq, prev, collection, rkey } = fields;
-    return canonicalize({ version, type, subject, issuer, record, issuedAt, seq, prev, collection, rkey });
-  }
-  return canonicalize({ version, type, subject, issuer, record, issuedAt });
-}
-
-/**
- * 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 async function computeRecordId(fields: SignedRecordSigningFields): Promise<string> {
-  return sha256(signedRecordSigningInput(fields));
-}
-
-/**
- * Compute SHA-256 hash of a string
- */
-async function sha256(message: string): Promise<string> {
-  // In React Native, use expo-crypto
-  if (isReactNative()) {
-    const Crypto = await loadExpoCrypto();
-    return Crypto.digestStringAsync(
-      Crypto.CryptoDigestAlgorithm.SHA256,
-      message
-    );
-  }
-
-  if (isNodeJS()) {
-    try {
-      const nodeCrypto = await loadNodeCrypto();
-      return nodeCrypto.createHash('sha256').update(message).digest('hex');
-    } catch (error) {
-      // Node crypto failed to load — log and fall through to Web Crypto API
-      logger.warn('[oxy.crypto] Node crypto unavailable, falling back to Web Crypto', { component: 'SignatureService' }, error);
-    }
-  }
-
-  // Browser: use Web Crypto API
-  const encoder = new TextEncoder();
-  const data = encoder.encode(message);
-  const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', data);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
-}
 
 export interface SignedMessage {
   message: string;
@@ -158,78 +76,15 @@ export class SignatureService {
   }
 
   /**
-   * Sign a message using the stored private key
+   * Sign a message using the stored device private key
    * Returns the signature in DER format (hex encoded)
    */
   static async sign(message: string): Promise<string> {
-    const keyPair = await KeyManager.getKeyPairObject();
-    if (!keyPair) {
+    const privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) {
       throw new Error('No identity found. Please create or import an identity first.');
     }
-
-    const messageHash = await sha256(message);
-    const signature = keyPair.sign(messageHash);
-    return signature.toDER('hex');
-  }
-
-  /**
-   * Sign a message with an explicit private key (without storing)
-   * Useful for one-time operations or testing
-   */
-  static async signWithKey(message: string, privateKey: string): Promise<string> {
-    const keyPair = ec.keyFromPrivate(privateKey);
-    const messageHash = await sha256(message);
-    const signature = keyPair.sign(messageHash);
-    return signature.toDER('hex');
-  }
-
-  /**
-   * Verify a signature against a message and public key
-   *
-   * Returns false on any error (invalid signature, malformed input, etc.).
-   * Errors are logged at debug level so they're available when troubleshooting
-   * signature mismatches but don't surface to the caller.
-   */
-  static async verify(message: string, signature: string, publicKey: string): Promise<boolean> {
-    try {
-      const key = ec.keyFromPublic(publicKey, 'hex');
-      const messageHash = await sha256(message);
-      return key.verify(messageHash, signature);
-    } catch (error) {
-      if (isDev()) {
-        logger.debug('[oxy.crypto] verify() returned false', { component: 'SignatureService' }, error);
-      }
-      return false;
-    }
-  }
-
-  /**
-   * Synchronous verification (for Node.js backend)
-   * Uses crypto module directly for hashing
-   * Note: This method should only be used in Node.js environments
-   */
-  static verifySync(message: string, signature: string, publicKey: string): boolean {
-    try {
-      if (!isNodeJS()) {
-        // In React Native, use async verify instead
-        throw new Error('verifySync should only be used in Node.js. Use verify() in React Native.');
-      }
-      // Intentionally using Function constructor here: this method is synchronous by design
-      // (Node.js backend hot-path) so we cannot use `await import()`. The Function constructor
-      // prevents Metro/bundlers from statically resolving the require. This is acceptable because
-      // verifySync is gated by isNodeJS() and will never execute in browser/RN environments.
-      // eslint-disable-next-line @typescript-eslint/no-implied-eval
-      const getCrypto = new Function('return require("crypto")');
-      const crypto = getCrypto();
-      const key = ec.keyFromPublic(publicKey, 'hex');
-      const messageHash = crypto.createHash('sha256').update(message).digest('hex');
-      return key.verify(messageHash, signature);
-    } catch (error) {
-      if (isDev()) {
-        logger.debug('[oxy.crypto] verifySync() returned false', { component: 'SignatureService' }, error);
-      }
-      return false;
-    }
+    return signMessage(message, privateKey);
   }
 
   /**
@@ -271,7 +126,7 @@ export class SignatureService {
 
     // Verify signature
     const messageWithTimestamp = `${message}:${timestamp}`;
-    return SignatureService.verify(messageWithTimestamp, signature, publicKey);
+    return verifySignature(messageWithTimestamp, signature, publicKey);
   }
 
   /**
@@ -303,9 +158,10 @@ export class SignatureService {
    * 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.
+   * `KeyManager` and signs with the protocol's explicit-key {@link signMessage}.
+   * 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).
@@ -319,7 +175,7 @@ export class SignatureService {
 
     const timestamp = Date.now();
     const message = `auth:${publicKey}:${challenge}:${timestamp}`;
-    const signature = await SignatureService.signWithKey(message, privateKey);
+    const signature = await signMessage(message, privateKey);
 
     return {
       challenge: signature,
@@ -345,7 +201,7 @@ export class SignatureService {
     }
 
     const message = `auth:${publicKey}:${originalChallenge}:${timestamp}`;
-    return SignatureService.verify(message, signature, publicKey);
+    return verifySignature(message, signature, publicKey);
   }
 
   /**
@@ -385,12 +241,12 @@ export class SignatureService {
     }
 
     const timestamp = Date.now();
-    
+
     // Create canonical string representation
     const sortedKeys = Object.keys(data).sort();
     const canonicalParts = sortedKeys.map(key => `${key}:${JSON.stringify(data[key])}`);
     const canonicalString = canonicalParts.join('|');
-    
+
     const message = `request:${publicKey}:${timestamp}:${canonicalString}`;
     const signature = await SignatureService.sign(message);
 
@@ -406,9 +262,11 @@ export class SignatureService {
    *
    * 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.
+   * and `signature`; `alg` is `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of
+   * the canonical bytes, DER-encoded). The cryptography is delegated to the
+   * protocol's {@link signEnvelope}, which derives the (uncompressed-hex)
+   * `publicKey` from the stored device key — identical to the registered
+   * verification method.
    *
    * Requires a stored identity (native secure storage); throws if none exists.
    *
@@ -421,35 +279,22 @@ export class SignatureService {
     subject: string,
     record: Record<string, unknown>,
   ): Promise<SignedRecordEnvelope> {
-    const publicKey = await KeyManager.getPublicKey();
-    if (!publicKey) {
+    const privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) {
       throw new Error('No identity found. Please create or import an identity first.');
     }
 
-    const version = 1 as const;
-    const issuer = subject;
-    const issuedAt = Date.now();
-    const signingInput = signedRecordSigningInput({
-      version,
-      type,
-      subject,
-      issuer,
-      record,
-      issuedAt,
-    });
-    const signature = await SignatureService.sign(signingInput);
-
-    return {
-      version,
-      type,
-      subject,
-      issuer,
-      record,
-      issuedAt,
-      publicKey,
-      alg: 'ES256K-DER-SHA256',
-      signature,
-    };
+    return signEnvelope(
+      {
+        version: 1,
+        type,
+        subject,
+        issuer: subject,
+        record,
+        issuedAt: Date.now(),
+      },
+      privateKey,
+    );
   }
 
   /**
@@ -457,8 +302,8 @@ export class SignatureService {
    * 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:
+   * `ES256K-DER-SHA256` scheme) 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).
@@ -478,60 +323,27 @@ export class SignatureService {
     record: Record<string, unknown>,
     chain: { seq: number; prev: string | null; collection: string; rkey: string },
   ): Promise<SignedRecordEnvelope> {
-    const publicKey = await KeyManager.getPublicKey();
-    if (!publicKey) {
+    const privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) {
       throw new Error('No identity found. Please create or import an identity first.');
     }
 
-    const version = 2 as const;
-    const issuer = subject;
-    const issuedAt = Date.now();
     const { seq, prev, collection, rkey } = chain;
-    const signingInput = signedRecordSigningInput({
-      version,
-      type,
-      subject,
-      issuer,
-      record,
-      issuedAt,
-      seq,
-      prev,
-      collection,
-      rkey,
-    });
-    const signature = await SignatureService.sign(signingInput);
-
-    return {
-      version,
-      type,
-      subject,
-      issuer,
-      record,
-      issuedAt,
-      seq,
-      prev,
-      collection,
-      rkey,
-      publicKey,
-      alg: 'ES256K-DER-SHA256',
-      signature,
-    };
-  }
-
-  /**
-   * 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 async verifyRecord(envelope: SignedRecordEnvelope): Promise<boolean> {
-    const signingInput = signedRecordSigningInput(envelope);
-    return SignatureService.verify(signingInput, envelope.signature, envelope.publicKey);
+    return signEnvelope(
+      {
+        version: 2,
+        type,
+        subject,
+        issuer: subject,
+        record,
+        issuedAt: Date.now(),
+        seq,
+        prev,
+        collection,
+        rkey,
+      },
+      privateKey,
+    );
   }
 }
 

package/src/index.ts

@@ -125,6 +125,7 @@ export type {
     TransferAccountOwnershipInput,
     CreateAccountCredentialInput,
     AccountSuccessResult,
+    SwitchAccountResult,
     // Applications owned within the account graph (Application = OAuth client).
     Application,
     ApplicationType,
@@ -263,9 +264,8 @@ export {
     IdentityPersistError,
 } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService, signedRecordSigningInput, computeRecordId } from './crypto/signatureService';
-export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
-export { canonicalize } from './crypto/canonicalJson';
+export { SignatureService } from './crypto/signatureService';
+export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 

package/src/mixins/OxyServices.accounts.ts

@@ -25,12 +25,16 @@
  * member `_id`, and credentials by their `credentialId`. Never by name, slug, or
  * handle.
  *
- * NOTE: acting-as (delegated identity) is NOT part of this mixin — `setActingAs`
- * / `getActingAs` live on `OxyServices.base` and `verifyActingAs` on the utility
- * mixin (it verifies against `GET /accounts/verify-acting-as`).
+ * SWITCHING INTO AN ACCOUNT: `switchToAccount(accountId)` mints a REAL session
+ * for the target account and plants it as the active session — there is no
+ * per-request "acting-as" header. Identity is carried by the session/token, not
+ * a delegation header, so a switch propagates through reload and `refresh-all`
+ * exactly like a login.
  */
 import type { User } from '../models/interfaces';
+import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { normalizeUserIdentity } from '../utils/userIdentity';
 import { CACHE_TIMES } from './mixinHelpers';
 
 // ---------------------------------------------------------------------------
@@ -427,6 +431,29 @@ export interface AccountSuccessResult {
   success: boolean;
 }
 
+/**
+ * Result of {@link OxyServicesAccountsMixin.switchToAccount} — the freshly
+ * minted session for the target account, in the SAME shape the canonical login
+ * / `claimSessionByToken` responses use (`SessionLoginResponse`), plus the
+ * device-local refresh-cookie slot index.
+ *
+ * `accessToken` is the first access token for the new session (already planted
+ * as the active token by `switchToAccount`). The refresh token is NOT in the
+ * body — the server sets it as the httpOnly `oxy_rt_<authuser>` cookie, which
+ * joins the device multi-account set so the switched session survives reload and
+ * propagates cross-domain via `/auth/refresh-all`. `user` is the target account.
+ */
+export interface SwitchAccountResult extends SessionLoginResponse {
+  /**
+   * The device-local refresh-cookie slot index (`oxy_rt_<authuser>`) the server
+   * assigned to the minted session. Surfaced so the consumer can register the
+   * new session in its device multi-account set exactly like a login response.
+   * Absent only when the server could not set the cookie (best-effort — the
+   * switch itself still succeeds).
+   */
+  authuser?: number;
+}
+
 export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -480,6 +507,67 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * Switch the active session INTO a managed account.
+     *
+     * Calls `POST /accounts/:id/switch` with the signed-in operator's bearer.
+     * The server authorises the operator (must hold `account:act_as` over the
+     * target, directly or inherited — else 403; 404 if missing/archived; 403 if
+     * the target is a personal account), then mints a REAL session for the
+     * target account and returns it in the canonical login / `claimSessionByToken`
+     * shape (`{ sessionId, deviceId, expiresAt, accessToken, user, authuser }`).
+     *
+     * Unlike the removed `X-Acting-As` delegation header, the returned session
+     * IS the new identity: this plants `accessToken` as the active token —
+     * exactly like `claimSessionByToken` / `verifyChallenge` — so every
+     * subsequent request authenticates as the target account. The refresh token
+     * is the server-set httpOnly `oxy_rt_<authuser>` cookie (never in the body),
+     * so it joins the device multi-account set and survives reload /
+     * `refresh-all` with no extra client work.
+     *
+     * After planting, the SDK's identity-scoped GET cache is fully cleared so
+     * every cached read re-fetches as the new account. (The consuming
+     * `OxyContext` additionally invalidates its React Query cache and updates
+     * session state from the returned `user`; this clears the SDK's own HTTP
+     * cache at the source — `setTokens` deliberately preserves the warm cache for
+     * same-user silent refreshes, so the sweep here is explicit.)
+     *
+     * @param accountId - The target account's Mongo `_id`.
+     * @returns The minted session (planted) plus the device `authuser` slot.
+     */
+    async switchToAccount(accountId: string): Promise<SwitchAccountResult> {
+      try {
+        const res = await this.makeRequest<SwitchAccountResult>(
+          'POST',
+          `/accounts/${encodeURIComponent(accountId)}/switch`,
+          undefined,
+          { cache: false },
+        );
+
+        // Plant the freshly minted session as the ACTIVE session, mirroring
+        // `claimSessionByToken` / `verifyChallenge`: the response body carries
+        // the first access token; the refresh token is the server-set httpOnly
+        // cookie, so there is nothing else to store here.
+        if (res?.accessToken) {
+          this.setTokens(res.accessToken);
+        }
+
+        // Identity changed → drop the entire GET response cache so no entry
+        // personalised for the previous identity is reused. Cache keys are
+        // identity-scoped, so a different identity could not READ the old
+        // entries anyway, but clearing guarantees a clean refetch as the new
+        // account and frees the prior identity's resident data.
+        this.clearCache();
+
+        return {
+          ...res,
+          user: normalizeUserIdentity(res.user),
+        };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Create a new (non-personal) account. The caller becomes its `owner`.
      * @param data - Account configuration: kind, optional parent, and profile.

package/src/mixins/OxyServices.assets.ts

@@ -1,6 +1,6 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { isReactNative } from '../utils/platform';
+import { isReactNative } from '@oxyhq/protocol';
 
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {

package/src/mixins/OxyServices.auth.ts

@@ -16,7 +16,7 @@ import type { PublicApplication } from './OxyServices.connectedApps';
 import { OxyAuthenticationError } from '../OxyServices.errors';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
-import { loadNodeCrypto } from '../utils/platformCrypto';
+import { loadNodeCrypto } from '@oxyhq/protocol';
 import { logger } from '../utils/loggerUtils';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 

package/src/mixins/OxyServices.civic.ts

@@ -49,17 +49,18 @@
  * session.
  */
 import type {
+  ChainHeadResponse,
   CredentialIssueResult,
   CredentialListResult,
   CredentialStatus,
   CredentialVerifyResult,
   ExportAttestation,
+  OxySignedRecordType,
   PersonhoodStatusResult,
   PublicCard,
   RealLifeAttestationResult,
   SignedPublicCard,
   SignedRecordEnvelope,
-  SignedRecordType,
   ValidationRequestSummary,
   ValidationVerdict,
   ValidationVoteResult,
@@ -67,7 +68,7 @@ import type {
   VouchResult,
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { canonicalize } from '../crypto/canonicalJson';
+import { canonicalize, verifySignature } from '@oxyhq/protocol';
 import { SignatureService } from '../crypto/signatureService';
 import { buildUserDid } from './OxyServices.identity';
 import { CACHE_TIMES } from './mixinHelpers';
@@ -290,7 +291,7 @@ export function parseAttestPayload(raw: string): ParsedAttestPayload | null {
  * key, matching the server which omits absent keys entirely) and checks the
  * `ES256K-DER-SHA256` signature against `attestation.publicKey`.
  *
- * NEVER throws: `SignatureService.verify` already swallows malformed-input
+ * NEVER throws: `verifySignature` already swallows malformed-input
  * errors and returns `false`, and an absent attestation short-circuits to
  * `false`. A pure, reusable helper (Commons can call it on a cached card).
  *
@@ -308,7 +309,7 @@ export async function verifyPublicCardAttestation(
   if (!signature || !publicKey) {
     return false;
   }
-  return SignatureService.verify(canonicalize(card), signature, publicKey);
+  return verifySignature(canonicalize(card), signature, publicKey);
 }
 
 /**
@@ -390,18 +391,6 @@ export interface RevokeCredentialResult {
   credential: VerifiableCredentialResponse;
 }
 
-/**
- * The current chain head as returned by `GET /identity/records/:userId/chain/head`.
- * `headRecordId` is `null` and `seq` is `-1` when the subject has no chain yet,
- * so the next record's coordinates are always `seq: head.seq + 1` (genesis = 0)
- * and `prev: head.headRecordId` (genesis = null).
- */
-interface ChainHeadResponse {
-  headRecordId: string | null;
-  seq: number;
-  recordCount: number;
-}
-
 export function OxyServicesCivicMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -929,7 +918,7 @@ export function OxyServicesCivicMixin<T extends typeof OxyServicesBase>(Base: T)
      * @param rkey - The AtProto-style record key within the collection.
      */
     async _signMyCivicRecordV2(
-      type: SignedRecordType,
+      type: OxySignedRecordType,
       record: Record<string, unknown>,
       collection: string,
       rkey: string,

package/src/mixins/OxyServices.identity.ts

@@ -28,6 +28,7 @@ import type {
   DidDocument,
   DomainVerificationInstructions,
   ExportBundle,
+  OxySignedRecordType,
   SignedRecordEnvelope,
   VerifiedDomain,
 } from '@oxyhq/contracts';
@@ -43,8 +44,13 @@ import { CACHE_TIMES } from './mixinHelpers';
  */
 const OXY_IDENTITY_APEX = 'oxy.so';
 
-/** Record categories a client may sign and publish. */
-export type IdentityRecordType = SignedRecordEnvelope['type'];
+/**
+ * Record categories a client may sign and publish to the Oxy store. The base
+ * envelope `type` is now an open string (any app may define its own records on
+ * the shared grammar); the Oxy identity store re-narrows it to the closed Oxy
+ * record set.
+ */
+export type IdentityRecordType = OxySignedRecordType;
 
 /** Auth-method types that can be unlinked via {@link OxyServicesIdentityMixin}. */
 export type UnlinkableAuthMethodType = 'identity' | 'password' | 'google' | 'apple' | 'github';