@seams/wallet-server 0.5.0

package/dist/types/shared-ts/src/near/actions.d.ts

@@ -0,0 +1,141 @@
+import type { DelegateAction, RelayedDelegateAction, Signature } from './delegate';
+export interface TransactionInput {
+    receiverId: string;
+    actions: ActionArgs[];
+}
+export interface TransactionInputWasm {
+    receiverId: string;
+    actions: ActionArgsWasm[];
+    nonce?: string;
+}
+export declare enum ActionType {
+    CreateAccount = "CreateAccount",
+    DeployContract = "DeployContract",
+    FunctionCall = "FunctionCall",
+    Transfer = "Transfer",
+    Stake = "Stake",
+    AddKey = "AddKey",
+    DeleteKey = "DeleteKey",
+    DeleteAccount = "DeleteAccount",
+    SignedDelegate = "SignedDelegate",
+    DeployGlobalContract = "DeployGlobalContract",
+    UseGlobalContract = "UseGlobalContract"
+}
+export declare enum TxExecutionStatus {
+    NONE = "NONE",
+    INCLUDED = "INCLUDED",
+    INCLUDED_FINAL = "INCLUDED_FINAL",
+    EXECUTED = "EXECUTED",
+    FINAL = "FINAL",
+    EXECUTED_OPTIMISTIC = "EXECUTED_OPTIMISTIC"
+}
+export interface FunctionCallAction {
+    type: ActionType.FunctionCall;
+    methodName: string;
+    args: Record<string, any>;
+    gas?: string;
+    deposit?: string;
+}
+export interface TransferAction {
+    type: ActionType.Transfer;
+    amount: string;
+}
+export interface CreateAccountAction {
+    type: ActionType.CreateAccount;
+}
+export interface DeployContractAction {
+    type: ActionType.DeployContract;
+    code: Uint8Array | string;
+}
+export interface DeployGlobalContractAction {
+    type: ActionType.DeployGlobalContract;
+    code: Uint8Array | string;
+    deployMode: 'CodeHash' | 'AccountId';
+}
+export interface UseGlobalContractAction {
+    type: ActionType.UseGlobalContract;
+    accountId?: string;
+    codeHash?: string;
+}
+export interface StakeAction {
+    type: ActionType.Stake;
+    stake: string;
+    publicKey: string;
+}
+export interface AddKeyAction {
+    type: ActionType.AddKey;
+    publicKey: string;
+    accessKey: {
+        nonce?: number;
+        permission: 'FullAccess' | {
+            FunctionCall: {
+                allowance?: string;
+                receiverId?: string;
+                methodNames?: string[];
+            };
+        };
+    };
+}
+export interface DeleteKeyAction {
+    type: ActionType.DeleteKey;
+    publicKey: string;
+}
+export interface DeleteAccountAction {
+    type: ActionType.DeleteAccount;
+    beneficiaryId: string;
+}
+export type ActionArgs = FunctionCallAction | TransferAction | CreateAccountAction | DeployContractAction | StakeAction | AddKeyAction | DeleteKeyAction | DeleteAccountAction | DeployGlobalContractAction | UseGlobalContractAction;
+export type ActionArgsWasm = {
+    action_type: ActionType.CreateAccount;
+} | {
+    action_type: ActionType.DeployContract;
+    code: number[];
+} | {
+    action_type: ActionType.FunctionCall;
+    method_name: string;
+    args: string;
+    gas: string;
+    deposit: string;
+} | {
+    action_type: ActionType.Transfer;
+    deposit: string;
+} | {
+    action_type: ActionType.Stake;
+    stake: string;
+    public_key: string;
+} | {
+    action_type: ActionType.AddKey;
+    public_key: string;
+    access_key: string;
+} | {
+    action_type: ActionType.DeleteKey;
+    public_key: string;
+} | {
+    action_type: ActionType.DeleteAccount;
+    beneficiary_id: string;
+} | {
+    action_type: ActionType.SignedDelegate;
+    delegate_action: DelegateAction;
+    signature: Signature;
+} | {
+    action_type: ActionType.DeployGlobalContract;
+    code: number[];
+    deploy_mode: 'CodeHash' | 'AccountId';
+} | {
+    action_type: ActionType.UseGlobalContract;
+    account_id?: string;
+    code_hash?: string;
+};
+export type RelayedSignedDelegateActionArgsWasm = {
+    action_type: ActionType.SignedDelegate;
+    delegate_action: RelayedDelegateAction;
+    signature: Signature;
+};
+export type NearTransactionActionArgsWasm = ActionArgsWasm | RelayedSignedDelegateActionArgsWasm;
+export declare function isActionArgsWasm(a?: any): a is ActionArgsWasm;
+export declare function toActionArgsWasm(action: ActionArgs): ActionArgsWasm;
+export declare function validateActionArgsWasm(actionArgsWasm: NearTransactionActionArgsWasm): void;
+export declare function fromActionArgsWasm(a: ActionArgsWasm): ActionArgs;
+export declare function fromTransactionInputWasm(tx: TransactionInputWasm): TransactionInput;
+export declare function fromTransactionInputsWasm(txs: TransactionInputWasm[]): TransactionInput[];
+//# sourceMappingURL=actions.d.ts.map

package/dist/types/shared-ts/src/near/delegate.d.ts

@@ -0,0 +1,55 @@
+import type { ActionArgs } from './actions';
+export interface PublicKey {
+    keyType: number;
+    keyData: number[];
+}
+export interface Signature {
+    keyType: number;
+    signatureData: number[];
+}
+export interface DelegateAction {
+    senderId: string;
+    receiverId: string;
+    actions: ActionArgs[];
+    nonce: bigint | string | number;
+    maxBlockHeight: bigint | string | number;
+    publicKey: PublicKey;
+}
+export interface SignedDelegate {
+    delegateAction: DelegateAction;
+    signature: Signature;
+}
+export interface RelayedNearFunctionCall {
+    readonly methodName: string;
+    readonly args: number[];
+    readonly gas: number;
+    readonly deposit: string;
+}
+export type RelayedNearAction = {
+    readonly functionCall: RelayedNearFunctionCall;
+} | {
+    readonly transfer: {
+        readonly deposit: string;
+    };
+};
+export interface RelayedDelegateAction {
+    readonly senderId: string;
+    readonly receiverId: string;
+    readonly actions: RelayedNearAction[];
+    readonly nonce: number;
+    readonly maxBlockHeight: number;
+    readonly publicKey: PublicKey;
+}
+export interface RelayedSignedDelegate {
+    readonly delegateAction: RelayedDelegateAction;
+    readonly signature: Signature;
+}
+export interface DelegateActionInput {
+    senderId: string;
+    receiverId: string;
+    actions: ActionArgs[];
+    nonce: bigint | string | number;
+    maxBlockHeight: bigint | string | number;
+    publicKey: string | PublicKey;
+}
+//# sourceMappingURL=delegate.d.ts.map

package/dist/types/shared-ts/src/near/index.d.ts

@@ -0,0 +1,3 @@
+export * from './actions';
+export * from './delegate';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/shared-ts/src/passkey-custody/ceremonyCommitPayload.d.ts

@@ -0,0 +1,211 @@
+/**
+ * What a wallet custody ceremony hands back when it seals.
+ *
+ * This is the wasm `WalletCustodyCommitPayloadV1` as it crosses the worker
+ * boundary and then the wire: ciphertext and public facts only. It lives in
+ * shared so the SDK worker channel and the Gateway commit path describe the
+ * same shape once — two spellings of it would diverge silently, and the first
+ * symptom would be a stored envelope that never opens.
+ *
+ * Nothing here is a capability. The seed, the owner roots, the manifest KEK,
+ * and the manifest proof all stayed inside the ceremony module.
+ */
+/**
+ * The owner key sets a ceremony can provision, spelled as the Rust
+ * `WalletKeySetKindV1` serializes them.
+ *
+ * Used where the SDK *chooses* a key set — the worker channel and the ceremony
+ * driver. `WalletCustodyCeremonyCommitPayload.keySet` stays a `string`: it
+ * arrives over the wire, and narrowing a parsed value to this union without
+ * checking it would only move the assumption somewhere harder to see.
+ */
+export type WalletCustodyKeySetKind = 'near_ed25519_v1' | 'evm_family_ecdsa_v1';
+export type WalletCustodyCeremonyRecoveryWrapPayload = {
+    readonly recoveryKeyId: string;
+    readonly nonceB64u: string;
+    readonly ciphertextB64u: string;
+    readonly aadHashB64u: string;
+};
+export type WalletCustodyRecoveryCodeLocatorPayload = {
+    readonly locatorB64u: string;
+    readonly recoveryKeyId: string;
+};
+/**
+ * The custody records a run writes when it *establishes* custody — the wallet's
+ * first key set. Absent when the run joined custody that already existed, which
+ * writes no envelope and issues no codes.
+ */
+export type EstablishedCustodyRecordsPayload = {
+    readonly envelopeId: string;
+    /**
+     * The envelope binding the ceremony sealed against, serialized verbatim.
+     * It is carried rather than rebuilt: this is what the AAD was computed over,
+     * so a reader that reassembled it from loose fields would produce an envelope
+     * that cannot open.
+     */
+    readonly envelopeBindingJson: string;
+    readonly envelopeNonceB64u: string;
+    readonly sealedCustodySecretB64u: string;
+    readonly envelopeAadHashB64u: string;
+    readonly envelopeCiphertextDigestB64u: string;
+    /** Ten wraps of one manifest KEK, one per recovery code. */
+    readonly recoveryManifestKekWraps: readonly WalletCustodyCeremonyRecoveryWrapPayload[];
+    /** Added by the browser after pairing each issued code with its wrap. */
+    readonly recoveryCodeLocators?: readonly WalletCustodyRecoveryCodeLocatorPayload[];
+    readonly recoveryEntryNonceB64u: string;
+    readonly recoveryEntryCiphertextB64u: string;
+    readonly recoveryEntryAadHashB64u: string;
+};
+export type RecoveryReplacementEnvelopePayload = {
+    readonly envelopeId: string;
+    readonly envelopeBindingJson: string;
+    readonly envelopeNonceB64u: string;
+    readonly sealedCustodySecretB64u: string;
+    readonly envelopeAadHashB64u: string;
+    readonly envelopeCiphertextDigestB64u: string;
+};
+export type WalletCustodyCeremonyCommitPayload = {
+    readonly walletId: string;
+    /** `near_ed25519_v1` or `evm_family_ecdsa_v1`: one key set per run. */
+    readonly keySet: string;
+    /**
+     * This key set's manifest digest, to be written onto that key set's own
+     * *registration state* — never to a record of its own. A free-standing
+     * manifest row could be deleted, and its absence would read as "not
+     * provisioned yet", silently narrowing the wallet.
+     */
+    readonly keyManifestDigestB64u: string;
+    /** Present only when this run established custody. */
+    readonly establishedCustody?: EstablishedCustodyRecordsPayload;
+    /** Set by the browser only after the issued codes were visibly acknowledged. */
+    readonly recoveryBackupAcknowledged?: true;
+    /** Present only when a recovery run resealed under the replacement passkey. */
+    readonly recoveryReplacementEnvelope?: RecoveryReplacementEnvelopePayload;
+    readonly registeredPublicKeyB64u?: string;
+    /**
+     * The NEAR same-device continuity cache: the activated Yao Client's material,
+     * sealed under a key derived from the wallet custody seed.
+     *
+     * Sealed under the seed rather than the factor that ran the ceremony, so
+     * every factor that opens the wallet's custody envelope reaches the same
+     * record — a wallet that registered under a passkey and later enrolled Email
+     * OTP would otherwise miss its cache on every OTP unlock.
+     *
+     * A cache and never a source of truth: losing it costs a Router round, not
+     * the wallet. It is also the only copy of this key set's signing material the
+     * ceremony produces, so a NEAR run that dropped it would register a public
+     * key with nothing to sign for it.
+     */
+    readonly ed25519LocalMaterialB64u?: string;
+    /** The nonce that record was sealed with. Generated inside the ceremony. */
+    readonly ed25519LocalMaterialNonceB64u?: string;
+    /**
+     * The application binding digest the cache was sealed against.
+     *
+     * Reported rather than recomputed at the reader: it is a field of the seal
+     * binding, and a reader that rebuilt it from loose application facts could
+     * differ by one byte and hold a record that never opens.
+     */
+    readonly ed25519ApplicationBindingDigestB64u?: string;
+    readonly clientRootPublicKey33B64u?: string;
+    /** Finalized role-local ECDSA material, still sealed to its own boundary. */
+    readonly ecdsaReadyStateBlobB64u?: string;
+    /**
+     * The EVM-family run's registered public identity, as its own finalize
+     * computed it. Absent on a NEAR run.
+     *
+     * The client's capability manifest is built from exactly these. They are
+     * reported rather than re-derived at the install site because re-deriving
+     * would mean trusting a second computation to agree with the one that
+     * produced the material.
+     */
+    readonly ecdsaPublicFacts?: WalletCustodyEvmFamilyPublicFacts;
+};
+export declare function walletCustodyCommitPayloadWithRecoveryBackupAcknowledgement(payload: WalletCustodyCeremonyCommitPayload): WalletCustodyCeremonyCommitPayload;
+export type WalletCustodyEvmFamilyPublicFacts = {
+    readonly contextBinding32B64u: string;
+    readonly derivationClientSharePublicKey33B64u: string;
+    readonly clientVerifyingShare33B64u: string;
+    readonly relayerPublicKey33B64u: string;
+    readonly groupPublicKey33B64u: string;
+    /** Lowercase 0x-prefixed. */
+    readonly ethereumAddress: string;
+    readonly clientShareRetryCounter: number;
+    readonly relayerShareRetryCounter: number;
+};
+/** Local EVM material returned only after the Router activation receipt. */
+export type WalletCustodyEvmFamilyActivationCompletion = {
+    readonly walletId: string;
+    readonly keyManifestDigestB64u: string;
+    readonly clientRootPublicKey33B64u: string;
+    readonly ecdsaReadyStateBlobB64u: string;
+    readonly ecdsaPublicFacts: WalletCustodyEvmFamilyPublicFacts;
+};
+/**
+ * What the registration leg reports back about the custody it was asked to
+ * commit — the response half of the same contract, so both halves stay in one
+ * place.
+ *
+ * **A registration leg never fails because of custody.** The wallet is already
+ * committed by the time custody is admitted, and the seed exists only in the
+ * client's worker, so the client is the one party that can retry, re-enter as a
+ * join, or abandon the run. Every outcome is therefore reported rather than
+ * thrown, and a client that sees anything but `committed` or `not_requested`
+ * must act on it rather than treat registration as done.
+ */
+export type WalletCustodyRegistrationOutcome = 
+/** No custody payload rode this leg. Registration is unaffected. */
+{
+    readonly status: 'not_requested';
+} | {
+    readonly status: 'committed';
+}
+/**
+ * A joining run: this key set's manifest digest, with no custody records
+ * written because the wallet already has its envelope and recovery set.
+ */
+ | {
+    readonly status: 'joined';
+    readonly keyManifestDigestB64u: string;
+}
+/**
+ * Another ceremony established this wallet's custody first. The client must
+ * discard its run's seed and re-enter as a join of the existing envelope.
+ */
+ | {
+    readonly status: 'custody_already_established';
+}
+/** The payload was refused. Nothing was written. */
+ | {
+    readonly status: 'rejected';
+    readonly reason: string;
+};
+/**
+ * Reads a commit payload off the wire without judging it.
+ *
+ * Deliberately total: it never throws and never reports a payload as absent
+ * when one was sent. Malformed custody must reach the admission gate and come
+ * back as a reported `rejected`, because the two outcomes lead the client
+ * somewhere completely different — `not_requested` says custody was never
+ * asked for, and a client that believed that would treat a wallet with no
+ * recoverable seed as fully registered.
+ *
+ * Nothing here validates. The nested `establishedCustody` is carried through
+ * verbatim: every one of its fields is parsed by the commit builder through the
+ * same boundary parsers every other reader uses, and anything it cannot parse
+ * becomes a rejection there.
+ */
+export declare function walletCustodyCeremonyCommitPayloadFromWire(value: unknown): WalletCustodyCeremonyCommitPayload | undefined;
+/** Decodes the exact EVM-family public facts emitted by custody WASM. */
+export declare function parseWalletCustodyEvmFamilyPublicFacts(value: unknown): WalletCustodyEvmFamilyPublicFacts;
+/** Decodes the exact EVM-family activation completion emitted by custody WASM. */
+export declare function parseWalletCustodyEvmFamilyActivationCompletion(value: unknown): WalletCustodyEvmFamilyActivationCompletion;
+/** Decodes the exact EVM-family commit payload emitted by custody WASM. */
+export declare function parseWalletCustodyEvmFamilyCommitPayload(value: unknown): WalletCustodyCeremonyCommitPayload;
+/**
+ * Parses the outcome a registration response carries. Throws, because this runs
+ * on the client against its own Gateway's response: an unrecognised custody
+ * status is a version skew the client must not paper over by guessing.
+ */
+export declare function parseWalletCustodyRegistrationOutcome(value: unknown, label: string): WalletCustodyRegistrationOutcome;
+//# sourceMappingURL=ceremonyCommitPayload.d.ts.map

package/dist/types/shared-ts/src/passkey-custody/credentialActivity.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What a user sees when managing the credentials that open their wallet.
+ *
+ * Purely descriptive: a label they chose and when the credential was last
+ * used. It is a *sibling* of the custody envelope, never a field on it —
+ * the envelope's AAD covers its own fields, so folding a mutable label into it
+ * would mean renaming a device rewrapped custody, and a failed rename could
+ * leave a wallet unopenable.
+ *
+ * It carries no secret, no authorization identity, and nothing that decides
+ * anything. Revocation reads the envelope's lifecycle, not this; a record that
+ * could withhold or grant access would be a second, weaker gate on custody.
+ */
+export type WalletCredentialActivityRecordV1 = {
+    readonly kind: 'wallet_credential_activity_v1';
+    readonly walletId: string;
+    /** The envelope this describes. One record per envelope. */
+    readonly envelopeId: string;
+    /**
+     * The user's name for the device. Absent until they set one — a blank label
+     * is not a name, and inventing "iPhone" from a user agent would present a
+     * guess as something they chose.
+     */
+    readonly label?: string;
+    readonly createdAtMs: number;
+    readonly updatedAtMs: number;
+    /**
+     * When custody was last opened with this credential. Absent when it has not
+     * been used since registration, which is different from "used at
+     * registration time" and should read that way in a list.
+     */
+    readonly lastUsedAtMs?: number;
+    /** How many times, for a user deciding whether a credential is stale. */
+    readonly useCount: number;
+};
+export declare const MAX_WALLET_CREDENTIAL_LABEL_LENGTH = 64;
+export type WalletCredentialActivityParseResult = {
+    readonly ok: true;
+    readonly record: WalletCredentialActivityRecordV1;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function parseWalletCredentialActivityRecordV1(raw: unknown, options: {
+    readonly expectedWalletId: string;
+}): WalletCredentialActivityParseResult;
+/** Records one use of a credential, for the list the user reads. */
+export declare function recordWalletCredentialUseV1(record: WalletCredentialActivityRecordV1, usedAtMs: number): WalletCredentialActivityRecordV1;
+//# sourceMappingURL=credentialActivity.d.ts.map

package/dist/types/shared-ts/src/passkey-custody/credentialObservations.d.ts

@@ -0,0 +1,74 @@
+import type { PasskeyEnvelopeId, WebAuthnCredentialIdB64u, WebAuthnRpId } from '../utils/domainIds';
+import type { EnvelopeRevision } from './primitives';
+/**
+ * Advisory credential metadata observed at registration.
+ *
+ * WebAuthn's backup-eligibility (BE) and backup-state (BS) flags describe how a
+ * provider may sync a credential. They do NOT prove that the provider will
+ * return the same PRF result on another device, so nothing in this module may
+ * be used to conclude that cross-device custody works. That conclusion has one
+ * source: an actual PRF result has sealed a server-held envelope.
+ */
+export type PasskeyCredentialObservationRecord = {
+    kind: 'passkey_credential_observation_v1';
+    rpId: WebAuthnRpId;
+    credentialIdB64u: WebAuthnCredentialIdB64u;
+    /** Whether the credential returned a usable PRF result when it was created. */
+    prfSupported: boolean;
+    /** WebAuthn BE flag: the provider may back this credential up. Advisory. */
+    backupEligible: boolean;
+    /** WebAuthn BS flag: the provider reports it is backed up now. Advisory. */
+    backupState: boolean;
+    observedAtMs: number;
+};
+/**
+ * Whether this wallet's custody can be opened on another device.
+ *
+ * `ready` is reachable only by presenting the active server-held envelope that
+ * a real PRF result sealed. Backup flags are not an input to this type, by
+ * construction: there is no branch they could satisfy.
+ */
+export type CrossDeviceCustodyReadiness = {
+    state: 'ready';
+    sealedEnvelopeId: PasskeyEnvelopeId;
+    envelopeRevision: EnvelopeRevision;
+} | {
+    state: 'not_ready';
+    reason: 'prf_unsupported' | 'no_sealed_envelope';
+};
+export declare function buildPasskeyCredentialObservationRecord(args: {
+    rpId: WebAuthnRpId;
+    credentialIdB64u: WebAuthnCredentialIdB64u;
+    prfSupported: boolean;
+    backupEligible: boolean;
+    backupState: boolean;
+    observedAtMs: number;
+}): PasskeyCredentialObservationRecord;
+export declare function parsePasskeyCredentialObservationRecord(raw: unknown, label?: string): PasskeyCredentialObservationRecord;
+export type WebAuthnBackupFlags = {
+    backupEligible: boolean;
+    backupState: boolean;
+};
+/**
+ * Reads the BE and BS flags from raw authenticator data.
+ *
+ * A credential reporting backed-up state is still not evidence of cross-device
+ * PRF continuity — see `resolveCrossDeviceCustodyReadiness`.
+ */
+export declare function parseWebAuthnBackupFlags(authenticatorData: Uint8Array): WebAuthnBackupFlags;
+/**
+ * Resolves cross-device custody readiness.
+ *
+ * Note the inputs: PRF support, and the active sealed envelope — never the
+ * backup flags. Registration may observe a backup-eligible, backed-up
+ * credential and this still returns `not_ready` until a PRF result has actually
+ * sealed a server-held envelope.
+ */
+export declare function resolveCrossDeviceCustodyReadiness(args: {
+    prfSupported: boolean;
+    activeSealedEnvelope: {
+        envelopeId: PasskeyEnvelopeId;
+        envelopeRevision: EnvelopeRevision;
+    } | null;
+}): CrossDeviceCustodyReadiness;
+//# sourceMappingURL=credentialObservations.d.ts.map