@oxy.so/core 7.23.2 → 7.24.0

package/dist/cjs/api/accounts.js

@@ -1,6 +1,39 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AccountsApi = exports.AccountInvitationsApi = exports.AccountAgentKeysApi = exports.AccountMembersApi = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.isOperatorSwitchTargetKind = exports.isDelegatedActAsEligibleKind = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_KINDS = exports.ACCOUNT_CATEGORY_IDS = void 0;
+exports.AccountsApi = exports.AccountInvitationsApi = exports.AccountIdentityKeyApi = exports.AccountAgentKeysApi = exports.AccountMembersApi = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.isOperatorSwitchTargetKind = exports.isDelegatedActAsEligibleKind = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_KINDS = exports.ACCOUNT_CATEGORY_IDS = void 0;
 const client_1 = require("@oxy.so/contracts/client");
 const userIdentity_1 = require("../utils/userIdentity");
 const identityCacheSweep_1 = require("../utils/identityCacheSweep");
@@ -88,6 +121,73 @@ class AccountAgentKeysApi {
     }
 }
 exports.AccountAgentKeysApi = AccountAgentKeysApi;
+/**
+ * `oxy.accounts.identityKey` — an organization's identity key (ADR 0061): its
+ * DID `#key-1`, the key Peable derives its FairCoin receive addresses from.
+ * Only the organization's owners and admins may read or change it; the key is
+ * created and held in Commons and never signs anybody in.
+ *
+ * `get` answers `publicKey: null` for an organization that has no key yet (its
+ * DID lists no `#key-1`): that is when a client shows its owners "Set up the
+ * organization's Peable wallet". A 403 (`ORGANIZATION_KEY_FORBIDDEN`) means the
+ * signed-in person is not an owner or admin of a claimed, active organization.
+ */
+class AccountIdentityKeyApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The organization's key (`null` without one) and every key it has had, oldest first. */
+    async get(accountId) {
+        return (0, client_1.parseContract)(client_1.organizationIdentityKeyStateCheck, await this.ctx.request('GET', `/accounts/${enc(accountId)}/identity-key`, undefined, { cache: false }));
+    }
+    /** A one-use challenge for one change, with the claims every signer signs. */
+    async requestChallenge(accountId, request) {
+        return (0, client_1.parseContract)(client_1.organizationKeyChallengeCheck, await this.ctx.request('POST', `/accounts/${enc(accountId)}/identity-key/challenge`, (0, client_1.parseContract)(client_1.organizationKeyChallengeRequestCheck, request), { cache: false }));
+    }
+    /** Apply a change with its signatures (see {@link link} for the whole ceremony). */
+    async apply(accountId, request) {
+        return (0, client_1.parseContract)(client_1.organizationIdentityKeyStateCheck, await this.ctx.request('POST', `/accounts/${enc(accountId)}/identity-key`, (0, client_1.parseContract)(client_1.organizationKeyApplyRequestCheck, request), { cache: false }));
+    }
+    /**
+     * Commons' whole ceremony. NATIVE-ONLY: the actor is THIS device's personal
+     * root (`KeyManager`), which must be the signed-in person's. `key` is the
+     * organization key the device generated (`create`, or `replace` with a new
+     * one); `previousKey` is the current organization key when the device holds
+     * it, so the replacement is recorded as proven by it.
+     */
+    async link(accountId, input) {
+        const { KeyManager, signIdentityProof } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        const [rootPrivateKey, rootPublicKey] = await Promise.all([
+            KeyManager.getPrivateKey(),
+            KeyManager.getPublicKey(),
+        ]);
+        if (!rootPrivateKey || !rootPublicKey) {
+            throw new Error('No identity on this device to sign with');
+        }
+        const challenge = await this.requestChallenge(accountId, {
+            operation: input.operation,
+            publicKey: input.key.publicKey,
+        });
+        const root = rootPublicKey.trim().toLowerCase();
+        if (challenge.actorPublicKey !== root) {
+            throw new Error("This device's identity is not the signed-in account's");
+        }
+        const sign = async (signer, publicKey) => (await signIdentityProof({ privateKey: signer.privateKey, publicKey }, (0, client_1.organizationKeyProofClaims)(challenge, publicKey))).signature;
+        const previousPublicKey = challenge.previousPublicKey;
+        return this.apply(accountId, {
+            operation: input.operation,
+            publicKey: challenge.publicKey,
+            challenge: challenge.challenge,
+            expiresAt: challenge.expiresAt,
+            actorSignature: await sign({ privateKey: rootPrivateKey, publicKey: root }, root),
+            keySignature: await sign(input.key, challenge.publicKey),
+            ...(input.previousKey && previousPublicKey
+                ? { previousKeySignature: await sign(input.previousKey, previousPublicKey) }
+                : {}),
+        });
+    }
+}
+exports.AccountIdentityKeyApi = AccountIdentityKeyApi;
 /** Consent-based invitations; never cached or queued as offline mutations. */
 class AccountInvitationsApi {
     constructor(ctx) {
@@ -123,6 +223,7 @@ class AccountsApi {
         this.members = new AccountMembersApi(ctx);
         this.invitations = new AccountInvitationsApi(ctx);
         this.agentKeys = new AccountAgentKeysApi(ctx);
+        this.identityKey = new AccountIdentityKeyApi(ctx);
     }
     /**
      * List the accounts the caller can access: their own personal (root)

package/dist/esm/api/accounts.js

@@ -1,4 +1,4 @@
-import { agentKeyListResponseCheck, agentKeyOperationChallengeCheck, agentKeyOperationCheck, agentKeyOperationResultCheck, executeAgentKeyOperationCheck, parseContract, } from '@oxy.so/contracts/client';
+import { agentKeyListResponseCheck, agentKeyOperationChallengeCheck, agentKeyOperationCheck, agentKeyOperationResultCheck, executeAgentKeyOperationCheck, organizationIdentityKeyStateCheck, organizationKeyApplyRequestCheck, organizationKeyChallengeCheck, organizationKeyChallengeRequestCheck, organizationKeyProofClaims, parseContract, } from '@oxy.so/contracts/client';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
 import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
 import { evictOxyAccountForestCache, oxyAccountDetailCacheKey, OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX, } from '../utils/accountCacheSweep.js';
@@ -75,6 +75,72 @@ export class AccountAgentKeysApi {
         return parseContract(agentKeyOperationResultCheck, response);
     }
 }
+/**
+ * `oxy.accounts.identityKey` — an organization's identity key (ADR 0061): its
+ * DID `#key-1`, the key Peable derives its FairCoin receive addresses from.
+ * Only the organization's owners and admins may read or change it; the key is
+ * created and held in Commons and never signs anybody in.
+ *
+ * `get` answers `publicKey: null` for an organization that has no key yet (its
+ * DID lists no `#key-1`): that is when a client shows its owners "Set up the
+ * organization's Peable wallet". A 403 (`ORGANIZATION_KEY_FORBIDDEN`) means the
+ * signed-in person is not an owner or admin of a claimed, active organization.
+ */
+export class AccountIdentityKeyApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The organization's key (`null` without one) and every key it has had, oldest first. */
+    async get(accountId) {
+        return parseContract(organizationIdentityKeyStateCheck, await this.ctx.request('GET', `/accounts/${enc(accountId)}/identity-key`, undefined, { cache: false }));
+    }
+    /** A one-use challenge for one change, with the claims every signer signs. */
+    async requestChallenge(accountId, request) {
+        return parseContract(organizationKeyChallengeCheck, await this.ctx.request('POST', `/accounts/${enc(accountId)}/identity-key/challenge`, parseContract(organizationKeyChallengeRequestCheck, request), { cache: false }));
+    }
+    /** Apply a change with its signatures (see {@link link} for the whole ceremony). */
+    async apply(accountId, request) {
+        return parseContract(organizationIdentityKeyStateCheck, await this.ctx.request('POST', `/accounts/${enc(accountId)}/identity-key`, parseContract(organizationKeyApplyRequestCheck, request), { cache: false }));
+    }
+    /**
+     * Commons' whole ceremony. NATIVE-ONLY: the actor is THIS device's personal
+     * root (`KeyManager`), which must be the signed-in person's. `key` is the
+     * organization key the device generated (`create`, or `replace` with a new
+     * one); `previousKey` is the current organization key when the device holds
+     * it, so the replacement is recorded as proven by it.
+     */
+    async link(accountId, input) {
+        const { KeyManager, signIdentityProof } = await import('../crypto/index.js');
+        const [rootPrivateKey, rootPublicKey] = await Promise.all([
+            KeyManager.getPrivateKey(),
+            KeyManager.getPublicKey(),
+        ]);
+        if (!rootPrivateKey || !rootPublicKey) {
+            throw new Error('No identity on this device to sign with');
+        }
+        const challenge = await this.requestChallenge(accountId, {
+            operation: input.operation,
+            publicKey: input.key.publicKey,
+        });
+        const root = rootPublicKey.trim().toLowerCase();
+        if (challenge.actorPublicKey !== root) {
+            throw new Error("This device's identity is not the signed-in account's");
+        }
+        const sign = async (signer, publicKey) => (await signIdentityProof({ privateKey: signer.privateKey, publicKey }, organizationKeyProofClaims(challenge, publicKey))).signature;
+        const previousPublicKey = challenge.previousPublicKey;
+        return this.apply(accountId, {
+            operation: input.operation,
+            publicKey: challenge.publicKey,
+            challenge: challenge.challenge,
+            expiresAt: challenge.expiresAt,
+            actorSignature: await sign({ privateKey: rootPrivateKey, publicKey: root }, root),
+            keySignature: await sign(input.key, challenge.publicKey),
+            ...(input.previousKey && previousPublicKey
+                ? { previousKeySignature: await sign(input.previousKey, previousPublicKey) }
+                : {}),
+        });
+    }
+}
 /** Consent-based invitations; never cached or queued as offline mutations. */
 export class AccountInvitationsApi {
     constructor(ctx) {
@@ -109,6 +175,7 @@ export class AccountsApi {
         this.members = new AccountMembersApi(ctx);
         this.invitations = new AccountInvitationsApi(ctx);
         this.agentKeys = new AccountAgentKeysApi(ctx);
+        this.identityKey = new AccountIdentityKeyApi(ctx);
     }
     /**
      * List the accounts the caller can access: their own personal (root)

package/dist/types/api/accounts.d.ts

@@ -18,7 +18,7 @@ import type { AccountAccessGrant, OrganizationType } from '@oxy.so/contracts';
  * no per-request "acting-as" header. Identity is carried by the session/token,
  * so a switch propagates through reload and cross-domain exactly like a login.
  */
-import type { AgentKeyOperation, AgentKeyOperationProof } from '@oxy.so/contracts';
+import type { AgentKeyOperation, AgentKeyOperationProof, OrganizationIdentityKeyState, OrganizationKeyApplyRequest, OrganizationKeyChallenge, OrganizationKeyChallengeRequest, OrganizationKeyOperation } from '@oxy.so/contracts';
 import type { User } from '../models/interfaces';
 import type { AccountCategoryId, AccountKind, AvatarCharacter, ChildAccountKind } from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
@@ -384,6 +384,44 @@ export declare class AccountAgentKeysApi {
         revokedMethodIds: string[];
     }>;
 }
+/** A secp256k1 key pair held on this device: lowercase hex, the public key uncompressed. */
+export interface OrganizationKeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+/**
+ * `oxy.accounts.identityKey` — an organization's identity key (ADR 0061): its
+ * DID `#key-1`, the key Peable derives its FairCoin receive addresses from.
+ * Only the organization's owners and admins may read or change it; the key is
+ * created and held in Commons and never signs anybody in.
+ *
+ * `get` answers `publicKey: null` for an organization that has no key yet (its
+ * DID lists no `#key-1`): that is when a client shows its owners "Set up the
+ * organization's Peable wallet". A 403 (`ORGANIZATION_KEY_FORBIDDEN`) means the
+ * signed-in person is not an owner or admin of a claimed, active organization.
+ */
+export declare class AccountIdentityKeyApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** The organization's key (`null` without one) and every key it has had, oldest first. */
+    get(accountId: string): Promise<OrganizationIdentityKeyState>;
+    /** A one-use challenge for one change, with the claims every signer signs. */
+    requestChallenge(accountId: string, request: OrganizationKeyChallengeRequest): Promise<OrganizationKeyChallenge>;
+    /** Apply a change with its signatures (see {@link link} for the whole ceremony). */
+    apply(accountId: string, request: OrganizationKeyApplyRequest): Promise<OrganizationIdentityKeyState>;
+    /**
+     * Commons' whole ceremony. NATIVE-ONLY: the actor is THIS device's personal
+     * root (`KeyManager`), which must be the signed-in person's. `key` is the
+     * organization key the device generated (`create`, or `replace` with a new
+     * one); `previousKey` is the current organization key when the device holds
+     * it, so the replacement is recorded as proven by it.
+     */
+    link(accountId: string, input: {
+        operation: OrganizationKeyOperation;
+        key: OrganizationKeyPair;
+        previousKey?: OrganizationKeyPair;
+    }): Promise<OrganizationIdentityKeyState>;
+}
 export interface AccountInvitation {
     id: string;
     accountId: string;
@@ -425,6 +463,8 @@ export declare class AccountsApi {
     readonly members: AccountMembersApi;
     readonly invitations: AccountInvitationsApi;
     readonly agentKeys: AccountAgentKeysApi;
+    /** An organization's identity key: its DID `#key-1` and Peable wallet key (ADR 0061). */
+    readonly identityKey: AccountIdentityKeyApi;
     constructor(ctx: OxyContext);
     /**
      * List the accounts the caller can access: their own personal (root)

package/dist/types/server/appAssertion.d.ts

@@ -23,8 +23,8 @@ export declare const oxyAppAssertionClaimsSchema: z.ZodObject<{
     sid: z.ZodString;
     app: z.ZodString;
     platform: z.ZodEnum<{
-        android: "android";
         ios: "ios";
+        android: "android";
         web: "web";
     }>;
     iat: z.ZodNumber;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.23.2",
+  "version": "7.24.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -181,7 +181,7 @@
   "dependencies": {
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@oxy.so/contracts": "^6.10.0",
+    "@oxy.so/contracts": "^6.11.0",
     "@oxy.so/protocol": "^1.6.1",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",

package/src/api/accounts.ts

@@ -18,13 +18,26 @@ import type { AccountAccessGrant, OrganizationType } from '@oxy.so/contracts';
  * no per-request "acting-as" header. Identity is carried by the session/token,
  * so a switch propagates through reload and cross-domain exactly like a login.
  */
-import type { AgentKeyOperation, AgentKeyOperationProof } from '@oxy.so/contracts';
+import type {
+  AgentKeyOperation,
+  AgentKeyOperationProof,
+  OrganizationIdentityKeyState,
+  OrganizationKeyApplyRequest,
+  OrganizationKeyChallenge,
+  OrganizationKeyChallengeRequest,
+  OrganizationKeyOperation,
+} from '@oxy.so/contracts';
 import {
   agentKeyListResponseCheck,
   agentKeyOperationChallengeCheck,
   agentKeyOperationCheck,
   agentKeyOperationResultCheck,
   executeAgentKeyOperationCheck,
+  organizationIdentityKeyStateCheck,
+  organizationKeyApplyRequestCheck,
+  organizationKeyChallengeCheck,
+  organizationKeyChallengeRequestCheck,
+  organizationKeyProofClaims,
   parseContract,
 } from '@oxy.so/contracts/client';
 import type { User } from '../models/interfaces';
@@ -457,6 +470,124 @@ export class AccountAgentKeysApi {
   }
 }
 
+/** A secp256k1 key pair held on this device: lowercase hex, the public key uncompressed. */
+export interface OrganizationKeyPair {
+  privateKey: string;
+  publicKey: string;
+}
+
+/**
+ * `oxy.accounts.identityKey` — an organization's identity key (ADR 0061): its
+ * DID `#key-1`, the key Peable derives its FairCoin receive addresses from.
+ * Only the organization's owners and admins may read or change it; the key is
+ * created and held in Commons and never signs anybody in.
+ *
+ * `get` answers `publicKey: null` for an organization that has no key yet (its
+ * DID lists no `#key-1`): that is when a client shows its owners "Set up the
+ * organization's Peable wallet". A 403 (`ORGANIZATION_KEY_FORBIDDEN`) means the
+ * signed-in person is not an owner or admin of a claimed, active organization.
+ */
+export class AccountIdentityKeyApi {
+  constructor(private readonly ctx: OxyContext) {}
+
+  /** The organization's key (`null` without one) and every key it has had, oldest first. */
+  async get(accountId: string): Promise<OrganizationIdentityKeyState> {
+    return parseContract(
+      organizationIdentityKeyStateCheck,
+      await this.ctx.request<unknown>(
+        'GET',
+        `/accounts/${enc(accountId)}/identity-key`,
+        undefined,
+        { cache: false },
+      ),
+    );
+  }
+
+  /** A one-use challenge for one change, with the claims every signer signs. */
+  async requestChallenge(
+    accountId: string,
+    request: OrganizationKeyChallengeRequest,
+  ): Promise<OrganizationKeyChallenge> {
+    return parseContract(
+      organizationKeyChallengeCheck,
+      await this.ctx.request<unknown>(
+        'POST',
+        `/accounts/${enc(accountId)}/identity-key/challenge`,
+        parseContract(organizationKeyChallengeRequestCheck, request),
+        { cache: false },
+      ),
+    );
+  }
+
+  /** Apply a change with its signatures (see {@link link} for the whole ceremony). */
+  async apply(
+    accountId: string,
+    request: OrganizationKeyApplyRequest,
+  ): Promise<OrganizationIdentityKeyState> {
+    return parseContract(
+      organizationIdentityKeyStateCheck,
+      await this.ctx.request<unknown>(
+        'POST',
+        `/accounts/${enc(accountId)}/identity-key`,
+        parseContract(organizationKeyApplyRequestCheck, request),
+        { cache: false },
+      ),
+    );
+  }
+
+  /**
+   * Commons' whole ceremony. NATIVE-ONLY: the actor is THIS device's personal
+   * root (`KeyManager`), which must be the signed-in person's. `key` is the
+   * organization key the device generated (`create`, or `replace` with a new
+   * one); `previousKey` is the current organization key when the device holds
+   * it, so the replacement is recorded as proven by it.
+   */
+  async link(
+    accountId: string,
+    input: {
+      operation: OrganizationKeyOperation;
+      key: OrganizationKeyPair;
+      previousKey?: OrganizationKeyPair;
+    },
+  ): Promise<OrganizationIdentityKeyState> {
+    const { KeyManager, signIdentityProof } = await import('../crypto/index');
+    const [rootPrivateKey, rootPublicKey] = await Promise.all([
+      KeyManager.getPrivateKey(),
+      KeyManager.getPublicKey(),
+    ]);
+    if (!rootPrivateKey || !rootPublicKey) {
+      throw new Error('No identity on this device to sign with');
+    }
+    const challenge = await this.requestChallenge(accountId, {
+      operation: input.operation,
+      publicKey: input.key.publicKey,
+    });
+    const root = rootPublicKey.trim().toLowerCase();
+    if (challenge.actorPublicKey !== root) {
+      throw new Error("This device's identity is not the signed-in account's");
+    }
+    const sign = async (signer: OrganizationKeyPair, publicKey: string) =>
+      (
+        await signIdentityProof(
+          { privateKey: signer.privateKey, publicKey },
+          organizationKeyProofClaims(challenge, publicKey),
+        )
+      ).signature;
+    const previousPublicKey = challenge.previousPublicKey;
+    return this.apply(accountId, {
+      operation: input.operation,
+      publicKey: challenge.publicKey,
+      challenge: challenge.challenge,
+      expiresAt: challenge.expiresAt,
+      actorSignature: await sign({ privateKey: rootPrivateKey, publicKey: root }, root),
+      keySignature: await sign(input.key, challenge.publicKey),
+      ...(input.previousKey && previousPublicKey
+        ? { previousKeySignature: await sign(input.previousKey, previousPublicKey) }
+        : {}),
+    });
+  }
+}
+
 export interface AccountInvitation {
   id: string;
   accountId: string;
@@ -540,11 +671,14 @@ export class AccountsApi {
   readonly members: AccountMembersApi;
   readonly invitations: AccountInvitationsApi;
   readonly agentKeys: AccountAgentKeysApi;
+  /** An organization's identity key: its DID `#key-1` and Peable wallet key (ADR 0061). */
+  readonly identityKey: AccountIdentityKeyApi;
 
   constructor(private readonly ctx: OxyContext) {
     this.members = new AccountMembersApi(ctx);
     this.invitations = new AccountInvitationsApi(ctx);
     this.agentKeys = new AccountAgentKeysApi(ctx);
+    this.identityKey = new AccountIdentityKeyApi(ctx);
   }
 
   /**