@xkova/sdk 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -124,6 +124,10 @@ const balance = await xkova.accountHolders.selfBalance({
 });
 ```
 
+`selfBalance` can return a partial answer. A chain not known right now has no
+entries in `balances` and a null `through_block` in `data_freshness`, so check
+that before treating a missing token as zero or adding balances together.
+
 ## Register a Hosted Auth application
 
 Hosted Auth provides an optional XKOVA-hosted sign-in flow. Register an
@@ -216,6 +220,26 @@ proofs, and manages session refresh and logout. Implement its session,
 authorization-transaction, and direct proof-exchange store contracts in your
 own database. It does not include a web framework or database adapter.
 
+`runExclusive` is an exclusivity boundary, not an all-or-nothing SQL
+transaction. Every awaited `put`, `replace` and `delete` must commit before
+returning, and remain committed if later callback work throws. Wrapping the
+whole callback in a rollback transaction can erase a staged proof after its
+one-time provider code was consumed. The same rule protects refresh-attempt
+checkpoints. Reconcile an uncertain write acknowledgement using the exact
+record and attempt identity, rather than starting a new operation.
+
+The package includes [a PostgreSQL checkpoint-store example](examples/postgres-checkpoint-store.mjs)
+and its [application-owned table definition](examples/postgres-checkpoints.sql).
+Install `pg` in your backend and apply the table definition through your own
+migration process. Instantiate separate stores with namespaces such as
+`authorization`, `sessions` and `exchange`, one shared pool and an existing
+32-byte application encryption key. The example uses session advisory locks
+across replicas, independent autocommit checkpoints, authenticated encryption
+bound to namespace/reference, exact replacement without upsert, and connection
+discard when lock release is uncertain. Do not use a transaction-pooling proxy
+for session locks. Own key rotation, pool deadlines and expired-record cleanup
+in your application; do not log records or encryption material.
+
 Authorization, Account Center, and action transactions expire within ten
 minutes of starting the request, or at the server's expiry if sooner. Late,
 expired, or excessively long-lived responses are rejected. Keep your BFF's
@@ -246,6 +270,51 @@ To exchange a proof without a browser callback, call `establishSession` with an
 `exchangeId`. Persist that ID before the first attempt and reuse it on retries.
 The store serializes attempts and preserves the exchange and session references.
 
+### Enroll an external identity-provider member
+
+For a registered OIDC connection, the confidential backend can call
+`memberAuth.enrollExternalMember({ externalSub, applicationConfigVersion,
+idempotencyKey })`. Use the exact opaque subject from a fully verified provider
+proof, the final read-back application configuration version, and one persisted
+operation key. Never link by email. The API derives issuer namespace, tenant,
+workspace and application from the registered connection and its bound
+`member_auth` API principal. The header selector and body selector must match.
+An existing issuer/subject membership is returned without replacing its identity,
+status or wallet bindings. A held or closed member remains held or closed.
+
+Enrollment creates or finds a membership, not an authenticated session or wallet.
+The normal nonce-bound provider-proof exchange remains required. For callback
+flows use `completeAuthorizationCallback`'s optional `ensureMemberEnrollment`
+hook. It runs after the one-time provider proof is durably staged, with a stable
+`idempotencyKey` preserved across retries. Verify the staged proof's signature,
+issuer, audience, algorithm, expiry and nonce, then call `enrollExternalMember`
+with its exact `sub`. Return that result from the hook. The helper checks that
+the resulting authenticated session resolves to the enrolled account holder.
+Do not put a fallible enrollment call inside `exchangeProviderCode`, before
+the provider result has been staged. A version conflict requires reviewing the
+changed registration and starting a new authorization flow, not blind retries.
+
+```ts
+const completion = await memberAuth.completeAuthorizationCallback({
+  ...callbackInput,
+  ensureMemberEnrollment: async ({ proofToken, idempotencyKey }) => {
+    // This application function performs full JOSE and exact nonce validation.
+    const verified = await verifyRegisteredProviderProof(proofToken);
+    return memberAuth.enrollExternalMember({
+      externalSub: verified.sub,
+      applicationConfigVersion: registration.config_version,
+      idempotencyKey,
+    });
+  },
+});
+```
+
+The verifier and `registration` are application prerequisites in this example,
+not SDK-provided provider validation or discovery functions. The public endpoint
+is `POST /v1/member-auth/enrollments`; it accepts no caller-selected account
+holder, tenant, issuer namespace, email or permissions. Enrollment alone never
+qualifies fresh action assurance, signing authority or settlement.
+
 ### Account Center and action callbacks
 
 Account Center accepts a same-origin `applicationReturnUri` and preserves it

package/dist/abi.d.ts

@@ -336,6 +336,14 @@ export declare const erc20XGaslessAbi: readonly [{
         readonly name: "";
         readonly type: "string";
         readonly internalType: "string";
+    }, {
+        readonly name: "";
+        readonly type: "uint8";
+        readonly internalType: "uint8";
+    }, {
+        readonly name: "";
+        readonly type: "address";
+        readonly internalType: "address";
     }, {
         readonly name: "";
         readonly type: "address";
@@ -362,6 +370,10 @@ export declare const erc20XGaslessAbi: readonly [{
         readonly name: "_symbol";
         readonly type: "string";
         readonly internalType: "string";
+    }, {
+        readonly name: "decimals_";
+        readonly type: "uint8";
+        readonly internalType: "uint8";
     }, {
         readonly name: "defaultAdmin";
         readonly type: "address";
@@ -370,6 +382,10 @@ export declare const erc20XGaslessAbi: readonly [{
         readonly name: "minter";
         readonly type: "address";
         readonly internalType: "address";
+    }, {
+        readonly name: "burner";
+        readonly type: "address";
+        readonly internalType: "address";
     }, {
         readonly name: "pauser";
         readonly type: "address";
@@ -1062,6 +1078,10 @@ export declare const erc20XGaslessAbi: readonly [{
     readonly type: "error";
     readonly name: "InvalidAddress";
     readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidDecimals";
+    readonly inputs: readonly [];
 }, {
     readonly type: "error";
     readonly name: "InvalidImplementation";
@@ -5482,6 +5502,14 @@ export declare const tokenizationAbis: {
             readonly name: "";
             readonly type: "string";
             readonly internalType: "string";
+        }, {
+            readonly name: "";
+            readonly type: "uint8";
+            readonly internalType: "uint8";
+        }, {
+            readonly name: "";
+            readonly type: "address";
+            readonly internalType: "address";
         }, {
             readonly name: "";
             readonly type: "address";
@@ -5508,6 +5536,10 @@ export declare const tokenizationAbis: {
             readonly name: "_symbol";
             readonly type: "string";
             readonly internalType: "string";
+        }, {
+            readonly name: "decimals_";
+            readonly type: "uint8";
+            readonly internalType: "uint8";
         }, {
             readonly name: "defaultAdmin";
             readonly type: "address";
@@ -5516,6 +5548,10 @@ export declare const tokenizationAbis: {
             readonly name: "minter";
             readonly type: "address";
             readonly internalType: "address";
+        }, {
+            readonly name: "burner";
+            readonly type: "address";
+            readonly internalType: "address";
         }, {
             readonly name: "pauser";
             readonly type: "address";
@@ -6208,6 +6244,10 @@ export declare const tokenizationAbis: {
         readonly type: "error";
         readonly name: "InvalidAddress";
         readonly inputs: readonly [];
+    }, {
+        readonly type: "error";
+        readonly name: "InvalidDecimals";
+        readonly inputs: readonly [];
     }, {
         readonly type: "error";
         readonly name: "InvalidImplementation";

package/dist/abi.js

@@ -443,6 +443,16 @@ export const erc20XGaslessAbi = [
                 "type": "string",
                 "internalType": "string"
             },
+            {
+                "name": "",
+                "type": "uint8",
+                "internalType": "uint8"
+            },
+            {
+                "name": "",
+                "type": "address",
+                "internalType": "address"
+            },
             {
                 "name": "",
                 "type": "address",
@@ -476,6 +486,11 @@ export const erc20XGaslessAbi = [
                 "type": "string",
                 "internalType": "string"
             },
+            {
+                "name": "decimals_",
+                "type": "uint8",
+                "internalType": "uint8"
+            },
             {
                 "name": "defaultAdmin",
                 "type": "address",
@@ -486,6 +501,11 @@ export const erc20XGaslessAbi = [
                 "type": "address",
                 "internalType": "address"
             },
+            {
+                "name": "burner",
+                "type": "address",
+                "internalType": "address"
+            },
             {
                 "name": "pauser",
                 "type": "address",
@@ -1376,6 +1396,11 @@ export const erc20XGaslessAbi = [
         "name": "InvalidAddress",
         "inputs": []
     },
+    {
+        "type": "error",
+        "name": "InvalidDecimals",
+        "inputs": []
+    },
     {
         "type": "error",
         "name": "InvalidImplementation",