@oxyhq/core 17.1.0 → 18.0.0

package/dist/types/index.d.ts

@@ -39,7 +39,7 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
-export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, UserCreatableAccountKind, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';

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

@@ -33,7 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
-import type { AccountKind, OrganizationCategory } from '@oxyhq/contracts';
+import type { AccountKind, OrganizationCategory, ChildAccountKind } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
@@ -131,12 +131,23 @@ export interface ListAccountsOptions {
      */
     tree?: boolean;
 }
-/** Kinds a signed-in user may create via `POST /accounts`. Channels are service-provisioned only. */
-export type UserCreatableAccountKind = 'organization' | 'project' | 'bot';
 /** Input accepted by `createAccount`. */
 export interface CreateAccountInput {
-    /** Classification of the new account. `personal` and `channel` are not creatable here. */
-    kind: UserCreatableAccountKind;
+    /**
+     * Classification of the new account. Every CHILD kind is creatable here with
+     * the caller's own bearer, `channel` included: a signed-in person has already
+     * proven who they are, and minting a child under their own tree is the same
+     * operation whichever kind it is.
+     *
+     * `channel` used to be excluded, on the reasoning that channels are
+     * service-provisioned only. What actually makes a channel safe does not depend
+     * on who creates it: `createChildAccount` writes no auth method, so it is born
+     * with no login, and `POST /accounts/:id/switch` refuses it via
+     * `isActAsEligibleKind`, so no session can ever have a channel as its subject
+     * and therefore no bearer exists that could add one. `personal` is excluded
+     * because it is a human login, minted at signup.
+     */
+    kind: ChildAccountKind;
     /**
      * Parent account `_id` to nest the new account under. Omitted → the API roots
      * it under the caller's personal account.

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

@@ -44,8 +44,9 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
          * `POST /session/device/token` — NO bearer, NO cookies: possession of the
          * secret IS the device-ownership proof. Returns a fresh short access token
-         * for the device's active account plus `nextDeviceSecret` (rotation-in-use)
-         * and the projected device-session `state`.
+         * for the device's active account plus `nextDeviceSecret` (on mint, the same
+         * proven secret echoed back — rotation happens on sign-in, not mint) and
+         * the projected device-session `state`.
          *
          * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
          * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-

package/dist/types/session/refresh.d.ts

@@ -34,10 +34,10 @@ export interface RefreshDeps {
  * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
  * the re-mint handler and the cold boot can react per the transport contract
  * without re-classifying the raw error:
- *  - `ok` — minted, persisted the rotated secret, planted the token.
+ *  - `ok` — minted, persisted `nextDeviceSecret`, planted the token.
  *  - `no-secret` — the store holds no `deviceId` + `deviceSecret` to mint from.
  *  - `invalid-secret` — 401 `invalid_device_secret`: the presented secret
- *    diverged (another tab/device rotated it past the grace window).
+ *    no longer matches the server's stored hash.
  *  - `no-session` — 401 `no_active_session`: the device is known but has no live
  *    session (authoritative signed-out).
  *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
@@ -45,10 +45,10 @@ export interface RefreshDeps {
  *    The device secret is FINE — it is the identity binding that went stale, so
  *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
- *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
- *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
- *    deliberately NOT planted: advertising a healthy session on a secret that
- *    will not survive a reload is exactly the divergence that logs users out.
+ *  - `persist-failed` — the mint succeeded but `nextDeviceSecret` could NOT be
+ *    durably persisted. The token is deliberately NOT planted: advertising a
+ *    healthy session on a secret that will not survive a reload is exactly the
+ *    divergence that logs users out.
  */
 export type DeviceSecretMintOutcome = {
     status: 'ok';
@@ -69,19 +69,14 @@ export type DeviceSecretMintOutcome = {
     status: 'persist-failed';
 };
 /**
- * Arm 1 — the rotating device-secret mint, run under the owning client's
- * PROCESS-WIDE single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ * Arm 1 — the device-secret mint, run under the owning client's PROCESS-WIDE
+ * single-flight (`httpService.runSingleFlightDeviceSecretMint`).
  *
- * The server ROTATES the presented `deviceSecret` on every successful mint and
- * the just-presented secret is valid only for a short grace window. If two lanes
- * (cold boot, the proactive scheduler, a request-time preflight, a 401 retry,
- * the socket token transport, or a tab-focus reconcile) minted concurrently they
- * would double-rotate the server and the durable store could converge on the
- * SUPERSEDED secret — after the grace window the next cold boot mint 401s and the
- * user is signed out. Routing EVERY lane through this one single-flight makes
- * concurrent callers await the SAME in-flight mint and all receive its result, so
- * there is exactly one rotation and the store always converges on the true
- * `current` secret.
+ * Concurrent lanes (cold boot, the proactive scheduler, a request-time preflight,
+ * a 401 retry, the socket token transport, or a tab-focus reconcile) must not
+ * each persist a different view of the mint response. Routing EVERY lane through
+ * this one single-flight makes concurrent callers await the SAME in-flight mint
+ * and all receive its result, so the durable store converges on one credential.
  *
  * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
  * the access token; a failed durable persist yields `persist-failed` WITHOUT

package/package.json

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

package/src/boot/sessionColdBoot.ts

@@ -227,10 +227,9 @@ export async function runSessionColdBoot(
   //    origin persisted a deviceId + deviceSecret, mint a short access token with
   //    a single bearer-less POST (no cookie, no navigation). The mint itself runs
   //    through `refreshDeviceSecretArm`, which acquires the client's PROCESS-WIDE
-  //    single-flight, persists the rotated `nextDeviceSecret` BEFORE planting the
-  //    token, and returns a classified outcome — so this step can never
-  //    double-rotate the server against the scheduler/transport/401 lanes, and
-  //    the durable store always converges on the true `current` secret.
+  //    single-flight, persists `nextDeviceSecret` BEFORE planting the token, and
+  //    returns a classified outcome — so concurrent mint lanes share one in-flight
+  //    request and the durable store always converges on the server's credential.
   steps.push({
     id: 'device-secret-mint',
     // Network step — skip entirely when the caller reports the device offline so
@@ -249,7 +248,7 @@ export async function runSessionColdBoot(
       const result = await refreshDeviceSecretArm({ oxy, store, pin });
       switch (result.status) {
         case 'ok':
-          // The arm persisted the rotated secret and planted the token.
+          // The arm persisted nextDeviceSecret and planted the token.
           return {
             kind: 'session',
             session: {

package/src/index.ts

@@ -136,7 +136,6 @@ export type {
     AccountCredentialWithSecret,
     RotateAccountCredentialResult,
     ListAccountsOptions,
-    UserCreatableAccountKind,
     CreateAccountInput,
     UpdateAccountInput,
     ProvisionChannelInput,

package/src/mixins/OxyServices.accounts.ts

@@ -33,7 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
-import type { AccountKind, OrganizationCategory } from '@oxyhq/contracts';
+import type { AccountKind, OrganizationCategory, ChildAccountKind } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { normalizeUserIdentity } from '../utils/userIdentity';
@@ -146,13 +146,23 @@ export interface ListAccountsOptions {
   tree?: boolean;
 }
 
-/** Kinds a signed-in user may create via `POST /accounts`. Channels are service-provisioned only. */
-export type UserCreatableAccountKind = 'organization' | 'project' | 'bot';
-
 /** Input accepted by `createAccount`. */
 export interface CreateAccountInput {
-  /** Classification of the new account. `personal` and `channel` are not creatable here. */
-  kind: UserCreatableAccountKind;
+  /**
+   * Classification of the new account. Every CHILD kind is creatable here with
+   * the caller's own bearer, `channel` included: a signed-in person has already
+   * proven who they are, and minting a child under their own tree is the same
+   * operation whichever kind it is.
+   *
+   * `channel` used to be excluded, on the reasoning that channels are
+   * service-provisioned only. What actually makes a channel safe does not depend
+   * on who creates it: `createChildAccount` writes no auth method, so it is born
+   * with no login, and `POST /accounts/:id/switch` refuses it via
+   * `isActAsEligibleKind`, so no session can ever have a channel as its subject
+   * and therefore no bearer exists that could add one. `personal` is excluded
+   * because it is a human login, minted at signup.
+   */
+  kind: ChildAccountKind;
   /**
    * Parent account `_id` to nest the new account under. Omitted → the API roots
    * it under the caller's personal account.

package/src/mixins/OxyServices.deviceBoot.ts

@@ -70,8 +70,9 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
      * `POST /session/device/token` — NO bearer, NO cookies: possession of the
      * secret IS the device-ownership proof. Returns a fresh short access token
-     * for the device's active account plus `nextDeviceSecret` (rotation-in-use)
-     * and the projected device-session `state`.
+     * for the device's active account plus `nextDeviceSecret` (on mint, the same
+     * proven secret echoed back — rotation happens on sign-in, not mint) and
+     * the projected device-session `state`.
      *
      * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
      * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-

package/src/session/refresh.ts

@@ -88,10 +88,10 @@ export interface RefreshDeps {
  * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
  * the re-mint handler and the cold boot can react per the transport contract
  * without re-classifying the raw error:
- *  - `ok` — minted, persisted the rotated secret, planted the token.
+ *  - `ok` — minted, persisted `nextDeviceSecret`, planted the token.
  *  - `no-secret` — the store holds no `deviceId` + `deviceSecret` to mint from.
  *  - `invalid-secret` — 401 `invalid_device_secret`: the presented secret
- *    diverged (another tab/device rotated it past the grace window).
+ *    no longer matches the server's stored hash.
  *  - `no-session` — 401 `no_active_session`: the device is known but has no live
  *    session (authoritative signed-out).
  *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
@@ -99,10 +99,10 @@ export interface RefreshDeps {
  *    The device secret is FINE — it is the identity binding that went stale, so
  *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
- *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
- *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
- *    deliberately NOT planted: advertising a healthy session on a secret that
- *    will not survive a reload is exactly the divergence that logs users out.
+ *  - `persist-failed` — the mint succeeded but `nextDeviceSecret` could NOT be
+ *    durably persisted. The token is deliberately NOT planted: advertising a
+ *    healthy session on a secret that will not survive a reload is exactly the
+ *    divergence that logs users out.
  */
 export type DeviceSecretMintOutcome =
   | { status: 'ok'; token: string; sessionId: string; userId: string }
@@ -114,19 +114,14 @@ export type DeviceSecretMintOutcome =
   | { status: 'persist-failed' };
 
 /**
- * Arm 1 — the rotating device-secret mint, run under the owning client's
- * PROCESS-WIDE single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ * Arm 1 — the device-secret mint, run under the owning client's PROCESS-WIDE
+ * single-flight (`httpService.runSingleFlightDeviceSecretMint`).
  *
- * The server ROTATES the presented `deviceSecret` on every successful mint and
- * the just-presented secret is valid only for a short grace window. If two lanes
- * (cold boot, the proactive scheduler, a request-time preflight, a 401 retry,
- * the socket token transport, or a tab-focus reconcile) minted concurrently they
- * would double-rotate the server and the durable store could converge on the
- * SUPERSEDED secret — after the grace window the next cold boot mint 401s and the
- * user is signed out. Routing EVERY lane through this one single-flight makes
- * concurrent callers await the SAME in-flight mint and all receive its result, so
- * there is exactly one rotation and the store always converges on the true
- * `current` secret.
+ * Concurrent lanes (cold boot, the proactive scheduler, a request-time preflight,
+ * a 401 retry, the socket token transport, or a tab-focus reconcile) must not
+ * each persist a different view of the mint response. Routing EVERY lane through
+ * this one single-flight makes concurrent callers await the SAME in-flight mint
+ * and all receive its result, so the durable store converges on one credential.
  *
  * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
  * the access token; a failed durable persist yields `persist-failed` WITHOUT
@@ -200,8 +195,8 @@ export async function refreshDeviceSecretArm(deps: {
       expiresAt: mint.expiresAt,
       ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
     };
-    // Rotation-in-use anti-loss: persist the NEXT secret and read-back-VERIFY it
-    // landed BEFORE planting the token. A failed durable persist must NOT plant.
+    // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
+    // A failed durable persist must NOT plant.
     const persistedOk = await store.save(next);
     if (!persistedOk) {
       return { status: 'persist-failed' };