@mantle-agent/custody 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @mantle-agent/custody
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Turnkey](https://www.turnkey.com) custody for Mantle Agent Accounts (Embedded Wallets model):
+
+- one **sub-organization per owner**, the owner (passkey) as sole root; email/SMS auth and recovery disabled;
+- one **wallet per agent**: `m/44'/60'/0'/0/0` is the agent EOA (root key), `/1` the session key;
+- the platform joins each sub-org as a **non-root delegated-access user**, added from the owner's own session;
+- a **session signing policy** that only lets the platform sign Calibur `SignedBatchedCall`s for that account and
+  chain, with that session key, executable only by the platform relayer, until the session expires.
+
+Server side (`@mantle-agent/custody`): `turnkeyClient`, `createOwnerSubOrg`, `verifyCustody`, `readAgentWallet`,
+`verifySessionPolicy`, `verifyOwnerStamp`, `sessionSigner`, `platformSelfRemove`.
+
+Browser side (`@mantle-agent/custody/owner`, no Node-only dependencies): `addPlatformDelegate`,
+`createAgentWallet`, `grantSessionSigning`, `renewSessionSigning`, `removePlatformDelegate`, `rootSigner`,
+`sessionSigningPolicy`.
+
+Notes from production use: Turnkey matches `signWith` case-sensitively (signers checksum it), the passkey stamp
+header is `X-Stamp-Webauthn`, and a freshly created sub-org can take a few seconds to become visible.

package/dist/custody.d.ts

@@ -0,0 +1,231 @@
+import { createAccountWithAddress } from "@turnkey/viem";
+import type { TCreatePoliciesBody, TCreateSubOrganizationBody, TCreateUsersBody, TCreateWalletAccountsBody, TCreateWalletBody, TDeletePoliciesBody, TDeleteUsersBody, TGetOrganizationConfigsBody, TGetPolicyBody, TGetUserBody, TGetUsersBody, TGetWalletAccountsBody, v1AuthenticatorParamsV2 } from "@turnkey/sdk-types";
+import { type Address } from "viem";
+import type { RootSigner, Signer } from "@mantle-agent/core";
+import { type SessionSigningScope } from "./policies.js";
+export declare const TURNKEY_API_BASE_URL = "https://api.turnkey.com";
+/** BIP-32 layout inside each agent's wallet: index 0 is the agent EOA (root), 1.. are session keys. */
+export declare const ROOT_KEY_PATH = "m/44'/60'/0'/0/0";
+export declare const sessionKeyPath: (index: number) => string;
+/**
+ * The calls each role makes. Turnkey's server client and its browser/passkey clients share these method names,
+ * so owner flows run unchanged on the confirmation page (passkey) and in tests (API key).
+ */
+export type ParentApi = {
+    createSubOrganization(body: TCreateSubOrganizationBody): Promise<{
+        subOrganizationId: string;
+        wallet?: {
+            walletId: string;
+            addresses: string[];
+        };
+        rootUserIds?: string[];
+    }>;
+    getOrganizationConfigs(body: TGetOrganizationConfigsBody): Promise<{
+        configs: {
+            quorum?: {
+                threshold: number;
+                userIds: string[];
+            };
+        };
+    }>;
+    getUsers(body: TGetUsersBody): Promise<{
+        users: {
+            userId: string;
+            userName: string;
+        }[];
+    }>;
+    getUser(body: TGetUserBody): Promise<{
+        user: {
+            userId: string;
+            apiKeys: {
+                credential: {
+                    publicKey: string;
+                };
+            }[];
+        };
+    }>;
+    getWalletAccounts(body: TGetWalletAccountsBody): Promise<{
+        accounts: {
+            walletId: string;
+            path: string;
+            address: string;
+            addressFormat: string;
+            curve: string;
+        }[];
+    }>;
+    getPolicy(body: TGetPolicyBody): Promise<{
+        policy: {
+            policyId: string;
+            effect: string;
+            consensus: string;
+            condition: string;
+            time?: string;
+        };
+    }>;
+};
+export type OwnerApi = {
+    createWallet(body: TCreateWalletBody): Promise<{
+        walletId: string;
+        addresses: string[];
+    }>;
+    createWalletAccounts(body: TCreateWalletAccountsBody): Promise<{
+        addresses: string[];
+    }>;
+    createUsers(body: TCreateUsersBody): Promise<{
+        userIds: string[];
+    }>;
+    createPolicies(body: TCreatePoliciesBody): Promise<{
+        policyIds: string[];
+    }>;
+    deletePolicies(body: TDeletePoliciesBody): Promise<unknown>;
+    deleteUsers(body: TDeleteUsersBody): Promise<unknown>;
+};
+export type DelegateApi = Pick<OwnerApi, "deleteUsers">;
+/** How the owner proves who they are: a passkey in production, an API key in tests and the PoC. */
+export type OwnerCredential = {
+    kind: "passkey";
+    authenticator: v1AuthenticatorParamsV2;
+} | {
+    kind: "apiKey";
+    publicKey: string;
+};
+export type OwnerSubOrg = {
+    subOrgId: string;
+    ownerUserId: string;
+};
+/**
+ * Backend step (parent org): the owner's own space, with the owner as the sole root user. All of the owner's
+ * agents live here as separate wallets (PRD IDN-04). Email/SMS auth and recovery are disabled so the parent org
+ * can never initiate an auth flow into it; the parent keeps read access only.
+ */
+export declare function createOwnerSubOrg(parent: ParentApi, params: {
+    name: string;
+    ownerName: string;
+    owner: OwnerCredential;
+}): Promise<OwnerSubOrg>;
+/** The wallet an agent gets: root key (agent EOA) at index 0, first session key at index 1. */
+export declare function agentWalletParams(params: {
+    subOrgId: string;
+    agentId: string;
+}): TCreateWalletBody;
+export type AgentWallet = {
+    walletId: string;
+    /** Agent EOA: becomes the 7702 account. Controlled only by the owner. */
+    rootAddress: Address;
+    sessionAddress: Address;
+};
+/** Owner step (confirmation page): create the agent's wallet in the owner's sub-org. */
+export declare function createAgentWallet(owner: OwnerApi, params: {
+    subOrgId: string;
+    agentId: string;
+}): Promise<AgentWallet>;
+/**
+ * Backend check: read the wallet back from Turnkey (parent read access) instead of trusting addresses the page
+ * reports, and require the root/session layout.
+ */
+export declare function readAgentWallet(reader: ParentApi, params: {
+    subOrgId: string;
+    walletId: string;
+}): Promise<AgentWallet>;
+/**
+ * Owner step (PRD WAL-07 key rotation): a new session key at `sessionKeyPath(index)` in the agent's wallet. A
+ * revoked key can never be granted again (the hook keeps it REVOKED), so re-authorizing needs a fresh one.
+ */
+export declare function addSessionKey(owner: OwnerApi, params: {
+    subOrgId: string;
+    walletId: string;
+    index: number;
+}): Promise<Address>;
+/** Backend check: the rotated session key, read back from Turnkey at the exact path. */
+export declare function readSessionKey(reader: ParentApi, params: {
+    subOrgId: string;
+    walletId: string;
+    index: number;
+}): Promise<Address>;
+/**
+ * Backend check: the policy the owner created must be exactly the one we asked for. A page that swapped in a
+ * broader policy (another key, no expiry, any executor) is caught here before the session goes live.
+ */
+export declare function verifySessionPolicy(reader: ParentApi, params: {
+    subOrgId: string;
+    policyId: string;
+    scope: SessionSigningScope;
+}): Promise<void>;
+/** A signed (stamped) Turnkey request produced on the owner's device, e.g. by TurnkeyClient.stampGetWhoami. */
+export type SignedTurnkeyRequest = {
+    body: string;
+    url: string;
+    stamp: {
+        stampHeaderName: string;
+        stampHeaderValue: string;
+    };
+};
+/**
+ * Owner login: forward a whoami request stamped with the owner's passkey (or session key) to Turnkey, which
+ * verifies the stamp. Only the whoami endpoint is forwarded, always to Turnkey, whatever URL the client sent.
+ */
+export declare function verifyOwnerStamp(signed: SignedTurnkeyRequest, opts?: {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    organizationId: string;
+    userId: string;
+}>;
+/**
+ * Owner step (runs in the owner's authenticated session): add the platform as a non-root API-key user with no
+ * permissions except deleting itself. Doing this from the owner's session means the platform is never in the
+ * root quorum, not even transiently.
+ */
+export declare function addPlatformDelegate(owner: OwnerApi, params: {
+    subOrgId: string;
+    platformApiPublicKey: string;
+    userName?: string;
+}): Promise<{
+    daUserId: string;
+    policyIds: string[];
+}>;
+/** Owner step: authorize the platform to sign with one session key, scoped as in `sessionSigningPolicy`. */
+export declare function grantSessionSigning(owner: OwnerApi, params: {
+    subOrgId: string;
+    scope: SessionSigningScope;
+}): Promise<string>;
+/** Owner step: same-key renewal. The new policy is created before the old one is removed, so signing never gaps. */
+export declare function renewSessionSigning(owner: OwnerApi, params: {
+    subOrgId: string;
+    previousPolicyId: string;
+    scope: SessionSigningScope;
+}): Promise<string>;
+/** Owner kill switch #2 (design 3.4): remove the platform user; this owner's agent can no longer sign. No gas. */
+export declare function removePlatformDelegate(owner: OwnerApi, params: {
+    subOrgId: string;
+    daUserId: string;
+}): Promise<void>;
+/** Platform kill switch #1 (design 3.4): the platform removes itself from a sub-org. Run across all sub-orgs. */
+export declare function platformSelfRemove(delegate: DelegateApi, params: {
+    subOrgId: string;
+    daUserId: string;
+}): Promise<unknown>;
+/**
+ * PRD risk "custody keeps root": after setup, the owner must be the only root user and the platform user must
+ * exist outside the quorum, holding the platform key. Trading stays blocked until this passes.
+ */
+export declare function verifyCustody(reader: ParentApi, params: {
+    subOrgId: string;
+    ownerUserId: string;
+    daUserId: string;
+    platformApiPublicKey: string;
+}): Promise<void>;
+type AnyTurnkeyClient = Parameters<typeof createAccountWithAddress>[0]["client"];
+/** Wallet Service side: the session key, reachable only through the platform DA credentials and its policy. */
+export declare function sessionSigner(params: {
+    client: AnyTurnkeyClient;
+    subOrgId: string;
+    sessionAddress: Address;
+}): Signer;
+/** Owner side: the root key (agent EOA). In production `client` is the owner's passkey session. */
+export declare function rootSigner(params: {
+    client: AnyTurnkeyClient;
+    subOrgId: string;
+    rootAddress: Address;
+}): RootSigner;
+export {};

package/dist/custody.js

@@ -0,0 +1,231 @@
+import { createAccountWithAddress } from "@turnkey/viem";
+import { getAddress } from "viem";
+import { daSelfDeletePolicy, sessionSigningPolicy } from "./policies.js";
+export const TURNKEY_API_BASE_URL = "https://api.turnkey.com";
+/** BIP-32 layout inside each agent's wallet: index 0 is the agent EOA (root), 1.. are session keys. */
+export const ROOT_KEY_PATH = "m/44'/60'/0'/0/0";
+export const sessionKeyPath = (index) => `m/44'/60'/0'/0/${index}`;
+const ethAccount = (path, name) => ({
+    curve: "CURVE_SECP256K1",
+    pathFormat: "PATH_FORMAT_BIP32",
+    path,
+    addressFormat: "ADDRESS_FORMAT_ETHEREUM",
+    name,
+});
+/**
+ * Backend step (parent org): the owner's own space, with the owner as the sole root user. All of the owner's
+ * agents live here as separate wallets (PRD IDN-04). Email/SMS auth and recovery are disabled so the parent org
+ * can never initiate an auth flow into it; the parent keeps read access only.
+ */
+export async function createOwnerSubOrg(parent, params) {
+    const res = await parent.createSubOrganization({
+        subOrganizationName: params.name,
+        rootUsers: [
+            {
+                userName: params.ownerName,
+                apiKeys: params.owner.kind === "apiKey"
+                    ? [{ apiKeyName: "owner", publicKey: params.owner.publicKey, curveType: "API_KEY_CURVE_P256" }]
+                    : [],
+                authenticators: params.owner.kind === "passkey" ? [params.owner.authenticator] : [],
+                oauthProviders: [],
+            },
+        ],
+        rootQuorumThreshold: 1,
+        disableEmailRecovery: true,
+        disableEmailAuth: true,
+        disableSmsAuth: true,
+        disableOtpEmailAuth: true,
+    });
+    const ownerUserId = res.rootUserIds?.[0];
+    if (!ownerUserId)
+        throw new Error("sub-organization created without a root user");
+    return { subOrgId: res.subOrganizationId, ownerUserId };
+}
+/** The wallet an agent gets: root key (agent EOA) at index 0, first session key at index 1. */
+export function agentWalletParams(params) {
+    return {
+        organizationId: params.subOrgId,
+        walletName: `agent:${params.agentId}`,
+        accounts: [ethAccount(ROOT_KEY_PATH, "root"), ethAccount(sessionKeyPath(1), "session-1")],
+    };
+}
+/** Owner step (confirmation page): create the agent's wallet in the owner's sub-org. */
+export async function createAgentWallet(owner, params) {
+    const { walletId, addresses } = await owner.createWallet(agentWalletParams(params));
+    const [root, session] = addresses;
+    if (!root || !session)
+        throw new Error("wallet created without the expected accounts");
+    return { walletId, rootAddress: getAddress(root), sessionAddress: getAddress(session) };
+}
+/**
+ * Backend check: read the wallet back from Turnkey (parent read access) instead of trusting addresses the page
+ * reports, and require the root/session layout.
+ */
+export async function readAgentWallet(reader, params) {
+    const { accounts } = await reader.getWalletAccounts({ organizationId: params.subOrgId, walletId: params.walletId });
+    const at = (path) => accounts.find((a) => a.walletId === params.walletId &&
+        a.path === path &&
+        a.addressFormat === "ADDRESS_FORMAT_ETHEREUM" &&
+        a.curve === "CURVE_SECP256K1");
+    const root = at(ROOT_KEY_PATH);
+    const session = at(sessionKeyPath(1));
+    if (!root || !session)
+        throw new Error("wallet does not have the agent key layout");
+    return { walletId: params.walletId, rootAddress: getAddress(root.address), sessionAddress: getAddress(session.address) };
+}
+/**
+ * Owner step (PRD WAL-07 key rotation): a new session key at `sessionKeyPath(index)` in the agent's wallet. A
+ * revoked key can never be granted again (the hook keeps it REVOKED), so re-authorizing needs a fresh one.
+ */
+export async function addSessionKey(owner, params) {
+    const { addresses } = await owner.createWalletAccounts({
+        organizationId: params.subOrgId,
+        walletId: params.walletId,
+        accounts: [ethAccount(sessionKeyPath(params.index), `session-${params.index}`)],
+    });
+    if (!addresses[0])
+        throw new Error("session key was not created");
+    return getAddress(addresses[0]);
+}
+/** Backend check: the rotated session key, read back from Turnkey at the exact path. */
+export async function readSessionKey(reader, params) {
+    const { accounts } = await reader.getWalletAccounts({ organizationId: params.subOrgId, walletId: params.walletId });
+    const key = accounts.find((a) => a.walletId === params.walletId &&
+        a.path === sessionKeyPath(params.index) &&
+        a.addressFormat === "ADDRESS_FORMAT_ETHEREUM" &&
+        a.curve === "CURVE_SECP256K1");
+    if (!key)
+        throw new Error(`no session key at ${sessionKeyPath(params.index)}`);
+    return getAddress(key.address);
+}
+/**
+ * Backend check: the policy the owner created must be exactly the one we asked for. A page that swapped in a
+ * broader policy (another key, no expiry, any executor) is caught here before the session goes live.
+ */
+export async function verifySessionPolicy(reader, params) {
+    const { policy } = await reader.getPolicy({ organizationId: params.subOrgId, policyId: params.policyId });
+    const expected = sessionSigningPolicy(params.scope);
+    const mismatched = ["effect", "consensus", "condition", "time"].filter((k) => (policy[k] ?? "") !== (expected[k] ?? ""));
+    if (mismatched.length > 0)
+        throw new Error(`session policy differs from the prepared one: ${mismatched.join(", ")}`);
+}
+/**
+ * Owner login: forward a whoami request stamped with the owner's passkey (or session key) to Turnkey, which
+ * verifies the stamp. Only the whoami endpoint is forwarded, always to Turnkey, whatever URL the client sent.
+ */
+export async function verifyOwnerStamp(signed, opts = {}) {
+    // API-key stamper: "X-Stamp"; passkey (WebAuthn) stamper: "X-Stamp-Webauthn". Header names are case-insensitive.
+    const allowedHeaders = new Set(["x-stamp", "x-stamp-webauthn"]);
+    if (!allowedHeaders.has(signed.stamp.stampHeaderName.toLowerCase()))
+        throw new Error("unsupported stamp header");
+    const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? TURNKEY_API_BASE_URL}/public/v1/query/whoami`, {
+        method: "POST",
+        headers: { "content-type": "application/json", [signed.stamp.stampHeaderName]: signed.stamp.stampHeaderValue },
+        body: signed.body,
+    });
+    if (!res.ok)
+        throw new Error(`turnkey rejected the stamp: ${res.status} ${(await res.text().catch(() => "")).slice(0, 300)}`);
+    const who = (await res.json());
+    if (!who.organizationId || !who.userId)
+        throw new Error("unexpected whoami response");
+    return { organizationId: who.organizationId, userId: who.userId };
+}
+/**
+ * Owner step (runs in the owner's authenticated session): add the platform as a non-root API-key user with no
+ * permissions except deleting itself. Doing this from the owner's session means the platform is never in the
+ * root quorum, not even transiently.
+ */
+export async function addPlatformDelegate(owner, params) {
+    const { userIds } = await owner.createUsers({
+        organizationId: params.subOrgId,
+        users: [
+            {
+                userName: params.userName ?? "mantle-agent-platform",
+                apiKeys: [
+                    { apiKeyName: "platform", publicKey: params.platformApiPublicKey, curveType: "API_KEY_CURVE_P256" },
+                ],
+                authenticators: [],
+                oauthProviders: [],
+                userTags: [],
+            },
+        ],
+    });
+    const daUserId = userIds[0];
+    if (!daUserId)
+        throw new Error("delegate user was not created");
+    const { policyIds } = await owner.createPolicies({
+        organizationId: params.subOrgId,
+        policies: [daSelfDeletePolicy(daUserId)],
+    });
+    return { daUserId, policyIds };
+}
+/** Owner step: authorize the platform to sign with one session key, scoped as in `sessionSigningPolicy`. */
+export async function grantSessionSigning(owner, params) {
+    const { policyIds } = await owner.createPolicies({
+        organizationId: params.subOrgId,
+        policies: [sessionSigningPolicy(params.scope)],
+    });
+    const policyId = policyIds[0];
+    if (!policyId)
+        throw new Error("session policy was not created");
+    return policyId;
+}
+/** Owner step: same-key renewal. The new policy is created before the old one is removed, so signing never gaps. */
+export async function renewSessionSigning(owner, params) {
+    const policyId = await grantSessionSigning(owner, params);
+    await owner.deletePolicies({ organizationId: params.subOrgId, policyIds: [params.previousPolicyId] });
+    return policyId;
+}
+/** Owner kill switch #2 (design 3.4): remove the platform user; this owner's agent can no longer sign. No gas. */
+export async function removePlatformDelegate(owner, params) {
+    await owner.deleteUsers({ organizationId: params.subOrgId, userIds: [params.daUserId] });
+}
+/** Platform kill switch #1 (design 3.4): the platform removes itself from a sub-org. Run across all sub-orgs. */
+export async function platformSelfRemove(delegate, params) {
+    return delegate.deleteUsers({ organizationId: params.subOrgId, userIds: [params.daUserId] });
+}
+/**
+ * PRD risk "custody keeps root": after setup, the owner must be the only root user and the platform user must
+ * exist outside the quorum, holding the platform key. Trading stays blocked until this passes.
+ */
+export async function verifyCustody(reader, params) {
+    const { configs } = await reader.getOrganizationConfigs({ organizationId: params.subOrgId });
+    const quorum = configs.quorum;
+    if (!quorum)
+        throw new Error("sub-organization has no root quorum");
+    if (quorum.userIds.length !== 1 || quorum.userIds[0] !== params.ownerUserId || quorum.threshold !== 1) {
+        throw new Error(`root quorum must be exactly the owner; got ${JSON.stringify(quorum)}`);
+    }
+    if (quorum.userIds.includes(params.daUserId))
+        throw new Error("platform user is in the root quorum");
+    // The delegate must hold the platform's key, not one the page made up.
+    const { user } = await reader.getUser({ organizationId: params.subOrgId, userId: params.daUserId });
+    if (!user.apiKeys.some((k) => k.credential.publicKey === params.platformApiPublicKey)) {
+        throw new Error("platform user does not hold the platform API key");
+    }
+}
+/** Wallet Service side: the session key, reachable only through the platform DA credentials and its policy. */
+export function sessionSigner(params) {
+    // Turnkey matches signWith case-sensitively against the checksummed address it stores.
+    const address = getAddress(params.sessionAddress);
+    return createAccountWithAddress({
+        client: params.client,
+        organizationId: params.subOrgId,
+        signWith: address,
+        ethereumAddress: address,
+    });
+}
+/** Owner side: the root key (agent EOA). In production `client` is the owner's passkey session. */
+export function rootSigner(params) {
+    const address = getAddress(params.rootAddress);
+    const account = createAccountWithAddress({
+        client: params.client,
+        organizationId: params.subOrgId,
+        signWith: address,
+        ethereumAddress: address,
+    });
+    if (!account.signAuthorization)
+        throw new Error("Turnkey account cannot sign 7702 authorizations");
+    return account;
+}
+//# sourceMappingURL=custody.js.map

package/dist/custody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custody.js","sourceRoot":"","sources":["../src/custody.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./policies.js";
+export * from "./custody.js";
+export * from "./server.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./policies.js";
+export * from "./custody.js";
+export * from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/owner.d.ts

@@ -0,0 +1,2 @@
+export * from "./policies.js";
+export * from "./custody.js";

package/dist/owner.js

@@ -0,0 +1,4 @@
+// Browser-safe entry: everything the confirmation page needs, without the Node-only server SDK.
+export * from "./policies.js";
+export * from "./custody.js";
+//# sourceMappingURL=owner.js.map

package/dist/owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.js","sourceRoot":"","sources":["../src/owner.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/policies.d.ts

@@ -0,0 +1,36 @@
+import { type Address, type Hex } from "viem";
+import type { v1CreatePolicyIntentV3 } from "@turnkey/sdk-types";
+export type PolicyIntent = v1CreatePolicyIntentV3;
+/** Everything the signing layer pins for one session. Mirrors what the account and AgentPolicyHook enforce. */
+export type SessionSigningScope = {
+    /** Turnkey user id of the platform's delegated-access (DA) user inside the owner's sub-org. */
+    daUserId: string;
+    /** Session key address (a wallet account in the owner's sub-org). */
+    sessionAddress: Address;
+    /** Calibur keyHash of the session key. */
+    keyHash: Hex;
+    /** The agent EOA (7702-delegated account); it is the EIP-712 verifyingContract. */
+    account: Address;
+    chainId: number;
+    /** Relayer address(es) allowed as SignedBatchedCall.executor. */
+    executors: readonly Address[];
+    /** Unix seconds; the policy stops applying afterwards (Turnkey trusted server time). */
+    expiresAt: number;
+};
+/**
+ * The only thing the platform may do with a user's keys: have the session key sign a Calibur SignedBatchedCall
+ * for this account, executable only by our relayer, until the session expires.
+ *
+ * Deliberately coarse (design: business rules live in AgentPolicyHook only). It isolates keys, so a leaked
+ * platform API key cannot sign with the root key, sign arbitrary messages or 7702 authorizations, or produce
+ * calls someone else could submit.
+ *
+ * Hex in EIP-712 conditions must be lowercase (Turnkey policy engine requirement); wallet account addresses are
+ * compared in their stored checksummed form.
+ */
+export declare function sessionSigningPolicy(scope: SessionSigningScope): PolicyIntent;
+/**
+ * Lets the DA user delete itself: the platform-wide emergency stop (no gas, immediate) and the response to a
+ * leaked platform key.
+ */
+export declare function daSelfDeletePolicy(daUserId: string): PolicyIntent;

package/dist/policies.js

@@ -0,0 +1,52 @@
+import { getAddress } from "viem";
+const quote = (s) => `'${s}'`;
+/**
+ * The only thing the platform may do with a user's keys: have the session key sign a Calibur SignedBatchedCall
+ * for this account, executable only by our relayer, until the session expires.
+ *
+ * Deliberately coarse (design: business rules live in AgentPolicyHook only). It isolates keys, so a leaked
+ * platform API key cannot sign with the root key, sign arbitrary messages or 7702 authorizations, or produce
+ * calls someone else could submit.
+ *
+ * Hex in EIP-712 conditions must be lowercase (Turnkey policy engine requirement); wallet account addresses are
+ * compared in their stored checksummed form.
+ */
+export function sessionSigningPolicy(scope) {
+    if (scope.executors.length === 0)
+        throw new Error("at least one executor is required");
+    const executors = scope.executors.map((e) => quote(e.toLowerCase())).join(", ");
+    const condition = [
+        "activity.type == 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2'",
+        "activity.params.encoding == 'PAYLOAD_ENCODING_EIP712'",
+        `wallet_account.address == ${quote(getAddress(scope.sessionAddress))}`,
+        "eth.eip_712.primary_type == 'SignedBatchedCall'",
+        "eth.eip_712.domain.name == 'Calibur'",
+        "eth.eip_712.domain.version == '1.0.0'",
+        `eth.eip_712.domain.chain_id == ${scope.chainId}`,
+        `eth.eip_712.domain.verifying_contract == ${quote(scope.account.toLowerCase())}`,
+        `eth.eip_712.message['keyHash'] == ${quote(scope.keyHash.toLowerCase())}`,
+        `eth.eip_712.message['executor'] in [${executors}]`,
+    ].join(" && ");
+    return {
+        policyName: `session:${scope.keyHash.toLowerCase()}`,
+        effect: "EFFECT_ALLOW",
+        consensus: `approvers.any(user, user.id == ${quote(scope.daUserId)})`,
+        condition,
+        time: `time.now < Timestamp(${quote(new Date(scope.expiresAt * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"))})`,
+        notes: `Agent session signing for ${scope.account} on chain ${scope.chainId}`,
+    };
+}
+/**
+ * Lets the DA user delete itself: the platform-wide emergency stop (no gas, immediate) and the response to a
+ * leaked platform key.
+ */
+export function daSelfDeletePolicy(daUserId) {
+    return {
+        policyName: "platform:self-delete",
+        effect: "EFFECT_ALLOW",
+        consensus: `approvers.any(user, user.id == ${quote(daUserId)})`,
+        condition: `activity.type == 'ACTIVITY_TYPE_DELETE_USERS' && activity.params.user_ids.count() == 1 && ${quote(daUserId)} in activity.params.user_ids`,
+        notes: "Platform delegated-access user may remove itself (emergency stop / key leak)",
+    };
+}
+//# sourceMappingURL=policies.js.map

package/dist/policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.js","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,MAAM,CAAC;AAsB1D,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAA0B;IAC7D,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvF,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChF,MAAM,SAAS,GAAG;QAChB,sDAAsD;QACtD,uDAAuD;QACvD,6BAA6B,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE;QACtE,iDAAiD;QACjD,sCAAsC;QACtC,uCAAuC;QACvC,kCAAkC,KAAK,CAAC,OAAO,EAAE;QACjD,4CAA4C,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE;QAChF,qCAAqC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE;QACzE,uCAAuC,SAAS,GAAG;KACpD,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEf,OAAO;QACL,UAAU,EAAE,WAAW,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE;QACpD,MAAM,EAAE,cAAc;QACtB,SAAS,EAAE,kCAAkC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG;QACrE,SAAS;QACT,IAAI,EAAE,wBAAwB,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG;QAChH,KAAK,EAAE,6BAA6B,KAAK,CAAC,OAAO,aAAa,KAAK,CAAC,OAAO,EAAE;KAC9E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO;QACL,UAAU,EAAE,sBAAsB;QAClC,MAAM,EAAE,cAAc;QACtB,SAAS,EAAE,kCAAkC,KAAK,CAAC,QAAQ,CAAC,GAAG;QAC/D,SAAS,EAAE,6FAA6F,KAAK,CAAC,QAAQ,CAAC,8BAA8B;QACrJ,KAAK,EAAE,8EAA8E;KACtF,CAAC;AACJ,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+export type ApiKeyCredentials = {
+    apiPublicKey: string;
+    apiPrivateKey: string;
+};
+/** Node only: a Turnkey API client authenticated with a P-256 API key (parent org, platform DA user, test owner). */
+export declare function turnkeyClient(params: ApiKeyCredentials & {
+    organizationId: string;
+    baseUrl?: string;
+}): import("@turnkey/sdk-server").TurnkeyApiClient;

package/dist/server.js

@@ -0,0 +1,12 @@
+import { Turnkey } from "@turnkey/sdk-server";
+import { TURNKEY_API_BASE_URL } from "./custody.js";
+/** Node only: a Turnkey API client authenticated with a P-256 API key (parent org, platform DA user, test owner). */
+export function turnkeyClient(params) {
+    return new Turnkey({
+        apiBaseUrl: params.baseUrl ?? TURNKEY_API_BASE_URL,
+        apiPublicKey: params.apiPublicKey,
+        apiPrivateKey: params.apiPrivateKey,
+        defaultOrganizationId: params.organizationId,
+    }).apiClient();
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIpD,qHAAqH;AACrH,MAAM,UAAU,aAAa,CAAC,MAAwE;IACpG,OAAO,IAAI,OAAO,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC,OAAO,IAAI,oBAAoB;QAClD,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,qBAAqB,EAAE,MAAM,CAAC,cAAc;KAC7C,CAAC,CAAC,SAAS,EAAE,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@mantle-agent/custody",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Turnkey custody for Mantle Agent Accounts: owner sub-orgs, agent wallets, delegated-access session signing policies and read-back verification. Browser-safe entry at /owner.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantle-xyz/mantle-agentic-meme-launchpad-account.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./owner": {
+      "source": "./src/owner.ts",
+      "types": "./dist/owner.d.ts",
+      "default": "./dist/owner.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@turnkey/crypto": "^2.13.3",
+    "@turnkey/sdk-server": "^8.8.0",
+    "@turnkey/sdk-types": "^1.11.0",
+    "@turnkey/viem": "^0.14.48",
+    "viem": "^2.57.14",
+    "@mantle-agent/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@turnkey/api-key-stamper": "^0.6.18",
+    "@turnkey/http": "^6.7.0",
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5",
+    "@mantle-agent/testkit": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }

package/src/custody.ts

@@ -0,0 +1,345 @@
+import { createAccountWithAddress } from "@turnkey/viem";
+import type {
+  TCreatePoliciesBody,
+  TCreateSubOrganizationBody,
+  TCreateUsersBody,
+  TCreateWalletAccountsBody,
+  TCreateWalletBody,
+  TDeletePoliciesBody,
+  TDeleteUsersBody,
+  TGetOrganizationConfigsBody,
+  TGetPolicyBody,
+  TGetUserBody,
+  TGetUsersBody,
+  TGetWalletAccountsBody,
+  v1AuthenticatorParamsV2,
+} from "@turnkey/sdk-types";
+import { getAddress, type Address } from "viem";
+import type { RootSigner, Signer } from "@mantle-agent/core";
+import { daSelfDeletePolicy, sessionSigningPolicy, type SessionSigningScope } from "./policies.js";
+
+export const TURNKEY_API_BASE_URL = "https://api.turnkey.com";
+
+/** BIP-32 layout inside each agent's wallet: index 0 is the agent EOA (root), 1.. are session keys. */
+export const ROOT_KEY_PATH = "m/44'/60'/0'/0/0";
+export const sessionKeyPath = (index: number) => `m/44'/60'/0'/0/${index}`;
+
+const ethAccount = (path: string, name: string) => ({
+  curve: "CURVE_SECP256K1" as const,
+  pathFormat: "PATH_FORMAT_BIP32" as const,
+  path,
+  addressFormat: "ADDRESS_FORMAT_ETHEREUM" as const,
+  name,
+});
+
+/**
+ * The calls each role makes. Turnkey's server client and its browser/passkey clients share these method names,
+ * so owner flows run unchanged on the confirmation page (passkey) and in tests (API key).
+ */
+export type ParentApi = {
+  createSubOrganization(body: TCreateSubOrganizationBody): Promise<{
+    subOrganizationId: string;
+    wallet?: { walletId: string; addresses: string[] };
+    rootUserIds?: string[];
+  }>;
+  getOrganizationConfigs(body: TGetOrganizationConfigsBody): Promise<{
+    configs: { quorum?: { threshold: number; userIds: string[] } };
+  }>;
+  getUsers(body: TGetUsersBody): Promise<{ users: { userId: string; userName: string }[] }>;
+  getUser(body: TGetUserBody): Promise<{ user: { userId: string; apiKeys: { credential: { publicKey: string } }[] } }>;
+  getWalletAccounts(body: TGetWalletAccountsBody): Promise<{
+    accounts: { walletId: string; path: string; address: string; addressFormat: string; curve: string }[];
+  }>;
+  getPolicy(body: TGetPolicyBody): Promise<{
+    policy: { policyId: string; effect: string; consensus: string; condition: string; time?: string };
+  }>;
+};
+
+export type OwnerApi = {
+  createWallet(body: TCreateWalletBody): Promise<{ walletId: string; addresses: string[] }>;
+  createWalletAccounts(body: TCreateWalletAccountsBody): Promise<{ addresses: string[] }>;
+  createUsers(body: TCreateUsersBody): Promise<{ userIds: string[] }>;
+  createPolicies(body: TCreatePoliciesBody): Promise<{ policyIds: string[] }>;
+  deletePolicies(body: TDeletePoliciesBody): Promise<unknown>;
+  deleteUsers(body: TDeleteUsersBody): Promise<unknown>;
+};
+
+export type DelegateApi = Pick<OwnerApi, "deleteUsers">;
+
+/** How the owner proves who they are: a passkey in production, an API key in tests and the PoC. */
+export type OwnerCredential =
+  | { kind: "passkey"; authenticator: v1AuthenticatorParamsV2 }
+  | { kind: "apiKey"; publicKey: string };
+
+export type OwnerSubOrg = { subOrgId: string; ownerUserId: string };
+
+/**
+ * Backend step (parent org): the owner's own space, with the owner as the sole root user. All of the owner's
+ * agents live here as separate wallets (PRD IDN-04). Email/SMS auth and recovery are disabled so the parent org
+ * can never initiate an auth flow into it; the parent keeps read access only.
+ */
+export async function createOwnerSubOrg(
+  parent: ParentApi,
+  params: { name: string; ownerName: string; owner: OwnerCredential },
+): Promise<OwnerSubOrg> {
+  const res = await parent.createSubOrganization({
+    subOrganizationName: params.name,
+    rootUsers: [
+      {
+        userName: params.ownerName,
+        apiKeys:
+          params.owner.kind === "apiKey"
+            ? [{ apiKeyName: "owner", publicKey: params.owner.publicKey, curveType: "API_KEY_CURVE_P256" }]
+            : [],
+        authenticators: params.owner.kind === "passkey" ? [params.owner.authenticator] : [],
+        oauthProviders: [],
+      },
+    ],
+    rootQuorumThreshold: 1,
+    disableEmailRecovery: true,
+    disableEmailAuth: true,
+    disableSmsAuth: true,
+    disableOtpEmailAuth: true,
+  });
+  const ownerUserId = res.rootUserIds?.[0];
+  if (!ownerUserId) throw new Error("sub-organization created without a root user");
+  return { subOrgId: res.subOrganizationId, ownerUserId };
+}
+
+/** The wallet an agent gets: root key (agent EOA) at index 0, first session key at index 1. */
+export function agentWalletParams(params: { subOrgId: string; agentId: string }): TCreateWalletBody {
+  return {
+    organizationId: params.subOrgId,
+    walletName: `agent:${params.agentId}`,
+    accounts: [ethAccount(ROOT_KEY_PATH, "root"), ethAccount(sessionKeyPath(1), "session-1")],
+  };
+}
+
+export type AgentWallet = {
+  walletId: string;
+  /** Agent EOA: becomes the 7702 account. Controlled only by the owner. */
+  rootAddress: Address;
+  sessionAddress: Address;
+};
+
+/** Owner step (confirmation page): create the agent's wallet in the owner's sub-org. */
+export async function createAgentWallet(
+  owner: OwnerApi,
+  params: { subOrgId: string; agentId: string },
+): Promise<AgentWallet> {
+  const { walletId, addresses } = await owner.createWallet(agentWalletParams(params));
+  const [root, session] = addresses;
+  if (!root || !session) throw new Error("wallet created without the expected accounts");
+  return { walletId, rootAddress: getAddress(root), sessionAddress: getAddress(session) };
+}
+
+/**
+ * Backend check: read the wallet back from Turnkey (parent read access) instead of trusting addresses the page
+ * reports, and require the root/session layout.
+ */
+export async function readAgentWallet(
+  reader: ParentApi,
+  params: { subOrgId: string; walletId: string },
+): Promise<AgentWallet> {
+  const { accounts } = await reader.getWalletAccounts({ organizationId: params.subOrgId, walletId: params.walletId });
+  const at = (path: string) =>
+    accounts.find(
+      (a) =>
+        a.walletId === params.walletId &&
+        a.path === path &&
+        a.addressFormat === "ADDRESS_FORMAT_ETHEREUM" &&
+        a.curve === "CURVE_SECP256K1",
+    );
+  const root = at(ROOT_KEY_PATH);
+  const session = at(sessionKeyPath(1));
+  if (!root || !session) throw new Error("wallet does not have the agent key layout");
+  return { walletId: params.walletId, rootAddress: getAddress(root.address), sessionAddress: getAddress(session.address) };
+}
+
+/**
+ * Owner step (PRD WAL-07 key rotation): a new session key at `sessionKeyPath(index)` in the agent's wallet. A
+ * revoked key can never be granted again (the hook keeps it REVOKED), so re-authorizing needs a fresh one.
+ */
+export async function addSessionKey(owner: OwnerApi, params: { subOrgId: string; walletId: string; index: number }): Promise<Address> {
+  const { addresses } = await owner.createWalletAccounts({
+    organizationId: params.subOrgId,
+    walletId: params.walletId,
+    accounts: [ethAccount(sessionKeyPath(params.index), `session-${params.index}`)],
+  });
+  if (!addresses[0]) throw new Error("session key was not created");
+  return getAddress(addresses[0]);
+}
+
+/** Backend check: the rotated session key, read back from Turnkey at the exact path. */
+export async function readSessionKey(reader: ParentApi, params: { subOrgId: string; walletId: string; index: number }): Promise<Address> {
+  const { accounts } = await reader.getWalletAccounts({ organizationId: params.subOrgId, walletId: params.walletId });
+  const key = accounts.find(
+    (a) =>
+      a.walletId === params.walletId &&
+      a.path === sessionKeyPath(params.index) &&
+      a.addressFormat === "ADDRESS_FORMAT_ETHEREUM" &&
+      a.curve === "CURVE_SECP256K1",
+  );
+  if (!key) throw new Error(`no session key at ${sessionKeyPath(params.index)}`);
+  return getAddress(key.address);
+}
+
+/**
+ * Backend check: the policy the owner created must be exactly the one we asked for. A page that swapped in a
+ * broader policy (another key, no expiry, any executor) is caught here before the session goes live.
+ */
+export async function verifySessionPolicy(
+  reader: ParentApi,
+  params: { subOrgId: string; policyId: string; scope: SessionSigningScope },
+): Promise<void> {
+  const { policy } = await reader.getPolicy({ organizationId: params.subOrgId, policyId: params.policyId });
+  const expected = sessionSigningPolicy(params.scope);
+  const mismatched = (["effect", "consensus", "condition", "time"] as const).filter(
+    (k) => (policy[k] ?? "") !== (expected[k] ?? ""),
+  );
+  if (mismatched.length > 0) throw new Error(`session policy differs from the prepared one: ${mismatched.join(", ")}`);
+}
+
+/** A signed (stamped) Turnkey request produced on the owner's device, e.g. by TurnkeyClient.stampGetWhoami. */
+export type SignedTurnkeyRequest = {
+  body: string;
+  url: string;
+  stamp: { stampHeaderName: string; stampHeaderValue: string };
+};
+
+/**
+ * Owner login: forward a whoami request stamped with the owner's passkey (or session key) to Turnkey, which
+ * verifies the stamp. Only the whoami endpoint is forwarded, always to Turnkey, whatever URL the client sent.
+ */
+export async function verifyOwnerStamp(
+  signed: SignedTurnkeyRequest,
+  opts: { baseUrl?: string; fetchImpl?: typeof fetch } = {},
+): Promise<{ organizationId: string; userId: string }> {
+  // API-key stamper: "X-Stamp"; passkey (WebAuthn) stamper: "X-Stamp-Webauthn". Header names are case-insensitive.
+  const allowedHeaders = new Set(["x-stamp", "x-stamp-webauthn"]);
+  if (!allowedHeaders.has(signed.stamp.stampHeaderName.toLowerCase())) throw new Error("unsupported stamp header");
+  const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? TURNKEY_API_BASE_URL}/public/v1/query/whoami`, {
+    method: "POST",
+    headers: { "content-type": "application/json", [signed.stamp.stampHeaderName]: signed.stamp.stampHeaderValue },
+    body: signed.body,
+  });
+  if (!res.ok) throw new Error(`turnkey rejected the stamp: ${res.status} ${(await res.text().catch(() => "")).slice(0, 300)}`);
+  const who = (await res.json()) as { organizationId?: string; userId?: string };
+  if (!who.organizationId || !who.userId) throw new Error("unexpected whoami response");
+  return { organizationId: who.organizationId, userId: who.userId };
+}
+
+/**
+ * Owner step (runs in the owner's authenticated session): add the platform as a non-root API-key user with no
+ * permissions except deleting itself. Doing this from the owner's session means the platform is never in the
+ * root quorum, not even transiently.
+ */
+export async function addPlatformDelegate(
+  owner: OwnerApi,
+  params: { subOrgId: string; platformApiPublicKey: string; userName?: string },
+): Promise<{ daUserId: string; policyIds: string[] }> {
+  const { userIds } = await owner.createUsers({
+    organizationId: params.subOrgId,
+    users: [
+      {
+        userName: params.userName ?? "mantle-agent-platform",
+        apiKeys: [
+          { apiKeyName: "platform", publicKey: params.platformApiPublicKey, curveType: "API_KEY_CURVE_P256" },
+        ],
+        authenticators: [],
+        oauthProviders: [],
+        userTags: [],
+      },
+    ],
+  });
+  const daUserId = userIds[0];
+  if (!daUserId) throw new Error("delegate user was not created");
+  const { policyIds } = await owner.createPolicies({
+    organizationId: params.subOrgId,
+    policies: [daSelfDeletePolicy(daUserId)],
+  });
+  return { daUserId, policyIds };
+}
+
+/** Owner step: authorize the platform to sign with one session key, scoped as in `sessionSigningPolicy`. */
+export async function grantSessionSigning(
+  owner: OwnerApi,
+  params: { subOrgId: string; scope: SessionSigningScope },
+): Promise<string> {
+  const { policyIds } = await owner.createPolicies({
+    organizationId: params.subOrgId,
+    policies: [sessionSigningPolicy(params.scope)],
+  });
+  const policyId = policyIds[0];
+  if (!policyId) throw new Error("session policy was not created");
+  return policyId;
+}
+
+/** Owner step: same-key renewal. The new policy is created before the old one is removed, so signing never gaps. */
+export async function renewSessionSigning(
+  owner: OwnerApi,
+  params: { subOrgId: string; previousPolicyId: string; scope: SessionSigningScope },
+): Promise<string> {
+  const policyId = await grantSessionSigning(owner, params);
+  await owner.deletePolicies({ organizationId: params.subOrgId, policyIds: [params.previousPolicyId] });
+  return policyId;
+}
+
+/** Owner kill switch #2 (design 3.4): remove the platform user; this owner's agent can no longer sign. No gas. */
+export async function removePlatformDelegate(owner: OwnerApi, params: { subOrgId: string; daUserId: string }) {
+  await owner.deleteUsers({ organizationId: params.subOrgId, userIds: [params.daUserId] });
+}
+
+/** Platform kill switch #1 (design 3.4): the platform removes itself from a sub-org. Run across all sub-orgs. */
+export async function platformSelfRemove(delegate: DelegateApi, params: { subOrgId: string; daUserId: string }) {
+  return delegate.deleteUsers({ organizationId: params.subOrgId, userIds: [params.daUserId] });
+}
+
+/**
+ * PRD risk "custody keeps root": after setup, the owner must be the only root user and the platform user must
+ * exist outside the quorum, holding the platform key. Trading stays blocked until this passes.
+ */
+export async function verifyCustody(
+  reader: ParentApi,
+  params: { subOrgId: string; ownerUserId: string; daUserId: string; platformApiPublicKey: string },
+): Promise<void> {
+  const { configs } = await reader.getOrganizationConfigs({ organizationId: params.subOrgId });
+  const quorum = configs.quorum;
+  if (!quorum) throw new Error("sub-organization has no root quorum");
+  if (quorum.userIds.length !== 1 || quorum.userIds[0] !== params.ownerUserId || quorum.threshold !== 1) {
+    throw new Error(`root quorum must be exactly the owner; got ${JSON.stringify(quorum)}`);
+  }
+  if (quorum.userIds.includes(params.daUserId)) throw new Error("platform user is in the root quorum");
+  // The delegate must hold the platform's key, not one the page made up.
+  const { user } = await reader.getUser({ organizationId: params.subOrgId, userId: params.daUserId });
+  if (!user.apiKeys.some((k) => k.credential.publicKey === params.platformApiPublicKey)) {
+    throw new Error("platform user does not hold the platform API key");
+  }
+}
+
+type AnyTurnkeyClient = Parameters<typeof createAccountWithAddress>[0]["client"];
+
+/** Wallet Service side: the session key, reachable only through the platform DA credentials and its policy. */
+export function sessionSigner(params: { client: AnyTurnkeyClient; subOrgId: string; sessionAddress: Address }): Signer {
+  // Turnkey matches signWith case-sensitively against the checksummed address it stores.
+  const address = getAddress(params.sessionAddress);
+  return createAccountWithAddress({
+    client: params.client,
+    organizationId: params.subOrgId,
+    signWith: address,
+    ethereumAddress: address,
+  });
+}
+
+/** Owner side: the root key (agent EOA). In production `client` is the owner's passkey session. */
+export function rootSigner(params: { client: AnyTurnkeyClient; subOrgId: string; rootAddress: Address }): RootSigner {
+  const address = getAddress(params.rootAddress);
+  const account = createAccountWithAddress({
+    client: params.client,
+    organizationId: params.subOrgId,
+    signWith: address,
+    ethereumAddress: address,
+  });
+  if (!account.signAuthorization) throw new Error("Turnkey account cannot sign 7702 authorizations");
+  return account as RootSigner;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./policies.js";
+export * from "./custody.js";
+export * from "./server.js";

package/src/owner.ts

@@ -0,0 +1,3 @@
+// Browser-safe entry: everything the confirmation page needs, without the Node-only server SDK.
+export * from "./policies.js";
+export * from "./custody.js";

package/src/policies.ts

@@ -0,0 +1,74 @@
+import { getAddress, type Address, type Hex } from "viem";
+import type { v1CreatePolicyIntentV3 } from "@turnkey/sdk-types";
+
+export type PolicyIntent = v1CreatePolicyIntentV3;
+
+/** Everything the signing layer pins for one session. Mirrors what the account and AgentPolicyHook enforce. */
+export type SessionSigningScope = {
+  /** Turnkey user id of the platform's delegated-access (DA) user inside the owner's sub-org. */
+  daUserId: string;
+  /** Session key address (a wallet account in the owner's sub-org). */
+  sessionAddress: Address;
+  /** Calibur keyHash of the session key. */
+  keyHash: Hex;
+  /** The agent EOA (7702-delegated account); it is the EIP-712 verifyingContract. */
+  account: Address;
+  chainId: number;
+  /** Relayer address(es) allowed as SignedBatchedCall.executor. */
+  executors: readonly Address[];
+  /** Unix seconds; the policy stops applying afterwards (Turnkey trusted server time). */
+  expiresAt: number;
+};
+
+const quote = (s: string) => `'${s}'`;
+
+/**
+ * The only thing the platform may do with a user's keys: have the session key sign a Calibur SignedBatchedCall
+ * for this account, executable only by our relayer, until the session expires.
+ *
+ * Deliberately coarse (design: business rules live in AgentPolicyHook only). It isolates keys, so a leaked
+ * platform API key cannot sign with the root key, sign arbitrary messages or 7702 authorizations, or produce
+ * calls someone else could submit.
+ *
+ * Hex in EIP-712 conditions must be lowercase (Turnkey policy engine requirement); wallet account addresses are
+ * compared in their stored checksummed form.
+ */
+export function sessionSigningPolicy(scope: SessionSigningScope): PolicyIntent {
+  if (scope.executors.length === 0) throw new Error("at least one executor is required");
+  const executors = scope.executors.map((e) => quote(e.toLowerCase())).join(", ");
+  const condition = [
+    "activity.type == 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2'",
+    "activity.params.encoding == 'PAYLOAD_ENCODING_EIP712'",
+    `wallet_account.address == ${quote(getAddress(scope.sessionAddress))}`,
+    "eth.eip_712.primary_type == 'SignedBatchedCall'",
+    "eth.eip_712.domain.name == 'Calibur'",
+    "eth.eip_712.domain.version == '1.0.0'",
+    `eth.eip_712.domain.chain_id == ${scope.chainId}`,
+    `eth.eip_712.domain.verifying_contract == ${quote(scope.account.toLowerCase())}`,
+    `eth.eip_712.message['keyHash'] == ${quote(scope.keyHash.toLowerCase())}`,
+    `eth.eip_712.message['executor'] in [${executors}]`,
+  ].join(" && ");
+
+  return {
+    policyName: `session:${scope.keyHash.toLowerCase()}`,
+    effect: "EFFECT_ALLOW",
+    consensus: `approvers.any(user, user.id == ${quote(scope.daUserId)})`,
+    condition,
+    time: `time.now < Timestamp(${quote(new Date(scope.expiresAt * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"))})`,
+    notes: `Agent session signing for ${scope.account} on chain ${scope.chainId}`,
+  };
+}
+
+/**
+ * Lets the DA user delete itself: the platform-wide emergency stop (no gas, immediate) and the response to a
+ * leaked platform key.
+ */
+export function daSelfDeletePolicy(daUserId: string): PolicyIntent {
+  return {
+    policyName: "platform:self-delete",
+    effect: "EFFECT_ALLOW",
+    consensus: `approvers.any(user, user.id == ${quote(daUserId)})`,
+    condition: `activity.type == 'ACTIVITY_TYPE_DELETE_USERS' && activity.params.user_ids.count() == 1 && ${quote(daUserId)} in activity.params.user_ids`,
+    notes: "Platform delegated-access user may remove itself (emergency stop / key leak)",
+  };
+}

package/src/server.ts

@@ -0,0 +1,15 @@
+import { Turnkey } from "@turnkey/sdk-server";
+import { TURNKEY_API_BASE_URL } from "./custody.js";
+
+export type ApiKeyCredentials = { apiPublicKey: string; apiPrivateKey: string };
+
+/** Node only: a Turnkey API client authenticated with a P-256 API key (parent org, platform DA user, test owner). */
+export function turnkeyClient(params: ApiKeyCredentials & { organizationId: string; baseUrl?: string }) {
+  return new Turnkey({
+    apiBaseUrl: params.baseUrl ?? TURNKEY_API_BASE_URL,
+    apiPublicKey: params.apiPublicKey,
+    apiPrivateKey: params.apiPrivateKey,
+    defaultOrganizationId: params.organizationId,
+  }).apiClient();
+}
+