@witnium-tech/witniumchain 0.9.0 → 0.11.0

package/FRONTEND-INTEGRATION.md

@@ -118,6 +118,36 @@ await client.login({ email, password });   // sets wac_session cookie
 In a browser the `wac_session` cookie is set automatically (the SDK uses
 `credentials: 'include'`). Server-side callers must capture + replay the cookie.
 
+### Cookie-only dashboard → bearer calls (automatic, no OAuth needed)
+
+You do **not** need to run the OAuth code flow to call the operational API
+(delegated keys, witness writes, chain reads). After `login()`, just call them:
+
+```ts
+await client.login({ email, password });   // sets wac_session
+await client.listDelegatedKeys();           // ← works; SDK mints a bearer token
+```
+
+How: those endpoints are bearer-only (they never accept the ambient cookie, so
+there's **no CSRF surface** even with `SameSite=None`). On the first such call
+the SDK transparently exchanges the session cookie for a short-lived access
+token via `POST /v1/auth/access-token`, caches it, and re-mints on a 401. You
+never see the token unless you want it:
+
+```ts
+const { accessToken, expiresAt } = await client.exchangeSessionForToken(); // optional pre-warm
+```
+
+Requirements: in the browser the `wac_session` cookie rides automatically
+(`credentials: 'include'`). Node/SSR callers pass `sessionCookie: '<value>'` to
+the constructor. If there's no valid session, the call throws a descriptive
+"requires an OAuth access token … or provide `sessionCookie`" error — that's
+your cue to send the user back to login.
+
+This is the recommended path for a first-party dashboard. Reach for the full
+OAuth flow below only when the dashboard is itself a registered OAuth client
+(e.g. third-party apps, or you want long-lived refresh tokens).
+
 ### Magic-link sign-in
 
 `beginOAuthLogin` / passwordless paths exist; see the SDK's `OauthNamespace`

package/dist/index.d.mts

@@ -242,6 +242,76 @@ interface paths$1 {
         patch?: never;
         trace?: never;
     };
+    "/v1/auth/access-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Exchange the session cookie for a bearer access token
+         * @description A logged-in (wac_session) user mints a short-lived OAuth-equivalent access token to call the bearer-only operational API (delegated keys, witness writes, chain reads). Keeps those endpoints off the ambient cookie (no CSRF surface). Same claim shape as an OAuth user token.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            accessToken: string;
+                            /** @enum {string} */
+                            tokenType: "Bearer";
+                            expiresIn: number;
+                            expiresAt: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/auth/login": {
         parameters: {
             query?: never;
@@ -10296,14 +10366,6 @@ type SetMemberRoleRequest = Req<'/v1/orgs/me/members/{userId}/role', 'put'>;
 type SetMemberRoleResponse = Res<'/v1/orgs/me/members/{userId}/role', 'put'>;
 type RemoveMemberResponse = Res<'/v1/orgs/me/members/{userId}', 'delete'>;
 type ResendInviteResponse = Res<'/v1/orgs/me/members/{userId}/resend-invite', 'post'>;
-type CreateOrganizationRequest = Req<'/v1/admin/organizations', 'post'>;
-type CreateOrganizationResponse = Res<'/v1/admin/organizations', 'post'>;
-type SetAccountTypeRequest = Req<'/v1/admin/organizations/{id}/account-type', 'patch'>;
-type SetAccountTypeResponse = Res<'/v1/admin/organizations/{id}/account-type', 'patch'>;
-type VerifyOrganizationResponse = Res<'/v1/admin/organizations/{id}/verify', 'patch'>;
-type RotateApiKeyResponse = Res<'/v1/admin/organizations/{id}/rotate-key', 'post'>;
-type AdjustCreditsRequest = Req<'/v1/admin/organizations/{id}/adjust-credits', 'post'>;
-type AdjustCreditsResponse = Res<'/v1/admin/organizations/{id}/adjust-credits', 'post'>;
 type ListDelegatedKeysResponse = Res<'/v1/users/me/delegated-keys', 'get'>;
 type PrepareDelegatedKeyRequest = Req<'/v1/users/me/delegated-keys', 'post'>;
 type PreparedDelegatedKeyResponse = Res<'/v1/users/me/delegated-keys', 'post'>;
@@ -10364,10 +10426,11 @@ type DashboardWitnessesResponse = ChainRes<'/v5/dashboard/witnesses', 'get'>;
  *
  * Covers both accounts (identity / billing / OAuth / delegated keys / witness
  * writes via the metered v5 proxy) and chain-api read surfaces (contract
- * info / witness lookup / wallet balance / dashboards). Three convenience
- * clients layer on top — `WitniumchainClient` (end-user),
- * `WitniumchainOrgClient` (org admin), `WitniumchainAdminClient` (sysadmin) —
- * with helpers for signup, subscriptions, and delegated-key provisioning.
+ * info / witness lookup / wallet balance / dashboards). Two convenience
+ * clients layer on top — `WitniumchainClient` (end-user) and
+ * `WitniumchainOrgClient` (org admin) — with helpers for signup,
+ * subscriptions, and delegated-key provisioning. The sysadmin surface lives in
+ * the separate PRIVATE `@witnium/chain-admin-sdk` package, not here.
  *
  * Stripe surface is intentionally Checkout + Customer Portal ONLY. Witnium is
  * not a marketplace, so there is no Stripe Connect onboarding.
@@ -10379,7 +10442,6 @@ type DashboardWitnessesResponse = ChainRes<'/v5/dashboard/witnesses', 'get'>;
  *   - sessionCookie  — `wac_session` value for browser-cookie routes.
  *   - accessToken    — OAuth Bearer JWT for end-user API.
  *   - orgApiKey      — `wcorg_live_…` for org admin.
- *   - adminToken     — sysadmin token.
  *   - signedRequest  — Ed25519 signer for SDK signed-request routes
  *                      (witnesses propose/sign/finalize/revoke). The SDK
  *                      does the canonical-message construction; you supply
@@ -10505,8 +10567,6 @@ interface WitniumchainClientConfig {
     verifierStorage?: PkceVerifierStorage;
     /** Organisation API key (`wcorg_live_…`). */
     orgApiKey?: string;
-    /** System-admin token (`Authorization: Bearer <ADMIN_TOKEN>`). */
-    adminToken?: string;
     /** Ed25519 signer for SDK signed-request routes (witness write ops). */
     signedRequest?: SignedRequestSigner;
     /** Per-request timeout in milliseconds. Default 30000. */
@@ -10580,6 +10640,8 @@ declare class WitniumchainClient {
     private readonly verifierStorage;
     private discoveryCache;
     private refreshInFlight;
+    private accessTokenFromSession;
+    private sessionExchangeInFlight;
     /** Subscriptions / billing helpers. See {@link Subscriptions}. */
     readonly subscriptions: Subscriptions;
     /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -10629,11 +10691,6 @@ declare class WitniumchainClient {
     getMyOrg(): Promise<PublicOrgResponse>;
     createOrgUser(body: CreateUserRequest): Promise<CreateUserResponse>;
     listOrgUsers(): Promise<ListUsersResponse>;
-    createOrganization(body: CreateOrganizationRequest): Promise<CreateOrganizationResponse>;
-    setOrgAccountType(id: string, body: SetAccountTypeRequest): Promise<SetAccountTypeResponse>;
-    verifyOrganization(id: string): Promise<VerifyOrganizationResponse>;
-    rotateOrgApiKey(id: string): Promise<RotateApiKeyResponse>;
-    adjustOrgCredits(id: string, body: AdjustCreditsRequest): Promise<AdjustCreditsResponse>;
     listDelegatedKeys(query?: {
         contractAddress?: string;
         active?: 'true' | 'false';
@@ -10754,6 +10811,41 @@ declare class WitniumchainClient {
      * instead of retrying with a now-invalid token.
      */
     refreshAccessToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Exchange the logged-in session (the `wac_session` cookie) for a short-lived
+     * bearer access token and cache it as the client's `accessToken`.
+     *
+     * This is the SDK side of the session→token model (accounts'
+     * `POST /v1/auth/access-token`): the dashboard authenticates with the
+     * cookie, but the operational API (delegated keys, witness writes, chain
+     * reads) is bearer-only — no endpoint accepts the ambient cookie, so there's
+     * no CSRF surface even with `SameSite=None`. The minted token is
+     * byte-compatible with an OAuth user token (same signing key, `iss`, `aud`,
+     * scope + org/role/contracts claims), so every `BearerJWT` route accepts it.
+     *
+     * Callers rarely invoke this directly — {@link applyAuth} mints transparently
+     * on the first `BearerJWT` call when no token is set and re-mints on a 401.
+     * It's exposed so a dashboard can pre-warm the token right after login.
+     *
+     * Requires a session: either `sessionCookie` on the constructor (Node) or an
+     * ambient `wac_session` cookie carried by the browser (`credentials:
+     * 'include'`). Throws {@link WitniumchainApiError} (401) when there's no
+     * valid session.
+     */
+    exchangeSessionForToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Best-effort transparent mint for the `BearerJWT` path: if no access token
+     * is cached, try the session exchange (single-flight). Swallows failure so
+     * the caller in {@link applyAuth} surfaces the actionable "no token / no
+     * session" guidance rather than a raw 401 from the exchange endpoint.
+     */
+    private ensureSessionAccessToken;
+    /**
+     * Obtain a fresh access token for a 401-retry, picking the right mechanism:
+     * an OAuth refresh when a refresh credential exists, else a session re-mint
+     * for a session-exchanged token. Returns true when a fresh token is in hand.
+     */
+    private reauthenticateForRetry;
     /**
      * End the OAuth session.
      *
@@ -10968,50 +11060,6 @@ declare class MfaRecoveryCodes {
     regenerate(): Promise<RecoveryCodesRegenerateResponse>;
 }
 
-interface WitniumchainAdminClientConfig {
-    /** Base URL, e.g. `https://auth.witniumchain.com`. Trailing slash optional. */
-    baseUrl: string;
-    /** System-admin token (`Authorization: Bearer <ADMIN_TOKEN>`). */
-    adminToken: string;
-    /** Per-request timeout in milliseconds. Default 30000. */
-    timeout?: number;
-    /** Alternate fetch implementation (e.g. for tests). Default `globalThis.fetch`. */
-    fetch?: typeof fetch;
-}
-type AccountType = 'metered' | 'unlimited';
-declare class WitniumchainAdminClient {
-    private readonly inner;
-    constructor(config: WitniumchainAdminClientConfig);
-    /**
-     * Mint a new organisation. The returned `apiKey` is shown ONCE — the server
-     * only retains its SHA-256 hash. Persist it before the response leaves
-     * scope; there is no recovery path.
-     *
-     * @param body  Organisation seed: name, email, optional accountType and
-     *              signup credit grant, optional skip-email-verification flag.
-     */
-    createOrganization(body: CreateOrganizationRequest): Promise<CreateOrganizationResponse>;
-    /** Flip an org between `metered` (Stripe checkout + credit ledger) and `unlimited` (flat-fee). */
-    setAccountType(orgId: string, accountType: AccountType): Promise<SetAccountTypeResponse>;
-    /** Mark an org's email as verified. Prerequisite for the org to create users. */
-    verifyEmail(orgId: string): Promise<VerifyOrganizationResponse>;
-    /**
-     * Rotate the org's API key. The previous `wcorg_live_…` is invalidated and
-     * the new key is returned ONCE — same one-time-secret semantics as
-     * {@link createOrganization}.
-     */
-    rotateApiKey(orgId: string): Promise<RotateApiKeyResponse>;
-    /**
-     * Apply a signed credit delta to an org's ledger. Positive `delta` grants
-     * credits (goodwill, migration backfill); negative claws them back.
-     * Recorded as `reason: adjustment` with the supplied `note`.
-     *
-     * Use sparingly — this bypasses Stripe and should be auditable from the
-     * `note` alone.
-     */
-    adjustCredits(orgId: string, delta: number, note?: string): Promise<AdjustCreditsResponse>;
-}
-
 type Body<T> = T extends {
     content: {
         'application/json': infer J;
@@ -11078,13 +11126,13 @@ declare class WitniumchainChainAdminClient {
  * Wraps the three `/v1/orgs/me/*` routes that org admins use to read their
  * own org profile and manage their users. This is the client B2B2C apps and
  * customer-admin dashboards consume — auth is the `wcorg_live_…` API key
- * minted via `WitniumchainAdminClient.createOrganization` or returned by
- * a subsequent `rotateApiKey`.
+ * minted by the sysadmin admin SDK or returned by a subsequent `rotateApiKey`.
  *
  * The surface is intentionally minimal — the underlying API only exposes
  * profile read + user create + user list. Anything more powerful (provision
  * credits, change account type, verify email) requires the sysadmin
- * `AdminToken` and therefore lives on `WitniumchainAdminClient`.
+ * `ADMIN_TOKEN` and lives in the PRIVATE `@witnium/chain-admin-sdk` package,
+ * never in this public SDK.
  */
 
 interface WitniumchainOrgClientConfig {
@@ -11202,4 +11250,4 @@ declare function buildRevokeSigningKeyPayload(args: {
     key: string;
 }): string;
 
-export { type AccountResponse, type AccountType, type paths$1 as AccountsPaths, type AddSigningKeyRequest$1 as AddSigningKeyRequest, type AddSigningKeyResponse, type AdjustCreditsRequest, type AdjustCreditsResponse, type BeginOAuthLoginArgs, type BeginOAuthLoginResult, type paths as ChainPaths, type CheckoutRequest, type CheckoutResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type CreateUserResponse, DelegatedKeys, type FinalizeWitnessResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetWitnessResponse, type HealthLiveResponse, type HealthReadyResponse, type InviteMemberRequest, type InviteMemberResponse, type LedgerResponse, type ListDelegatedKeysResponse, type ListOauthSessionsResponse, type ListUsersResponse, type LoginRequest, type LoginResponse, type LogoutResponse, type MembersListResponse, MfaNamespace, MfaRecoveryCodes, MfaTotp, type OAuthTokenSnapshot, OWNER_OP, OauthNamespace, OauthSessions, OrgMembers, OrgUsers, type OwnerOpName, type OwnerSigner, type PauseRequest$1 as PauseRequest, type PauseResponse, type PkceVerifierStorage, type PortalResponse, type PrepareDelegatedKeyRequest, type PreparedDelegatedKeyResponse, type ProposeWitnessRequest, type ProposeWitnessResponse, type ProvisionContractRequest, type ProvisionContractResponse, type ProvisionDelegatedKeyArgs, type ProvisionDelegatedKeyResult, type PublicOrgResponse, type RecoveryCodesRegenerateResponse, type ReissueProvisioningTokenResponse, type RemoveMemberResponse, type ResendInviteResponse, type ResetAccountResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDelegatedKeyResponse, type RevokeSigningKeyRequest$1 as RevokeSigningKeyRequest, type RevokeSigningKeyResponse, type RevokeWitnessRequest, type RevokeWitnessResponse, type RotateApiKeyResponse, type SetAccountTypeRequest, type SetAccountTypeResponse, type SetMemberRoleRequest, type SetMemberRoleResponse, type SignRequest, type SignResponse, type SignWitnessRequest, type SignWitnessResponse, type SignedRequestSigner, SigningKeys, type SignupRequest, type SignupResponse, type SubmitDelegatedKeyRequest, type SubmitDelegatedKeyResponse, Subscriptions, type SuspendMemberResponse, type TotpConfirmRequest, type TotpConfirmResponse, type TotpDisableResponse, type TotpEnrollResponse, type UnpauseRequest, type UnpauseResponse, type VerifyEmailResponse, type VerifyOrganizationResponse, WitniumchainAdminClient, type WitniumchainAdminClientConfig, WitniumchainApiError, WitniumchainChainAdminClient, type WitniumchainChainAdminClientConfig, WitniumchainClient, type WitniumchainClientConfig, WitniumchainOrgClient, type WitniumchainOrgClientConfig, buildAddSigningKeyPayload, buildPausePayload, buildRevokeSigningKeyPayload, buildUnpausePayload, defaultVerifierStorage };
+export { type AccountResponse, type paths$1 as AccountsPaths, type AddSigningKeyRequest$1 as AddSigningKeyRequest, type AddSigningKeyResponse, type BeginOAuthLoginArgs, type BeginOAuthLoginResult, type paths as ChainPaths, type CheckoutRequest, type CheckoutResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateUserRequest, type CreateUserResponse, DelegatedKeys, type FinalizeWitnessResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetWitnessResponse, type HealthLiveResponse, type HealthReadyResponse, type InviteMemberRequest, type InviteMemberResponse, type LedgerResponse, type ListDelegatedKeysResponse, type ListOauthSessionsResponse, type ListUsersResponse, type LoginRequest, type LoginResponse, type LogoutResponse, type MembersListResponse, MfaNamespace, MfaRecoveryCodes, MfaTotp, type OAuthTokenSnapshot, OWNER_OP, OauthNamespace, OauthSessions, OrgMembers, OrgUsers, type OwnerOpName, type OwnerSigner, type PauseRequest$1 as PauseRequest, type PauseResponse, type PkceVerifierStorage, type PortalResponse, type PrepareDelegatedKeyRequest, type PreparedDelegatedKeyResponse, type ProposeWitnessRequest, type ProposeWitnessResponse, type ProvisionContractRequest, type ProvisionContractResponse, type ProvisionDelegatedKeyArgs, type ProvisionDelegatedKeyResult, type PublicOrgResponse, type RecoveryCodesRegenerateResponse, type ReissueProvisioningTokenResponse, type RemoveMemberResponse, type ResendInviteResponse, type ResetAccountResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDelegatedKeyResponse, type RevokeSigningKeyRequest$1 as RevokeSigningKeyRequest, type RevokeSigningKeyResponse, type RevokeWitnessRequest, type RevokeWitnessResponse, type SetMemberRoleRequest, type SetMemberRoleResponse, type SignRequest, type SignResponse, type SignWitnessRequest, type SignWitnessResponse, type SignedRequestSigner, SigningKeys, type SignupRequest, type SignupResponse, type SubmitDelegatedKeyRequest, type SubmitDelegatedKeyResponse, Subscriptions, type SuspendMemberResponse, type TotpConfirmRequest, type TotpConfirmResponse, type TotpDisableResponse, type TotpEnrollResponse, type UnpauseRequest, type UnpauseResponse, type VerifyEmailResponse, WitniumchainApiError, WitniumchainChainAdminClient, type WitniumchainChainAdminClientConfig, WitniumchainClient, type WitniumchainClientConfig, WitniumchainOrgClient, type WitniumchainOrgClientConfig, buildAddSigningKeyPayload, buildPausePayload, buildRevokeSigningKeyPayload, buildUnpausePayload, defaultVerifierStorage };

package/dist/index.d.ts

@@ -242,6 +242,76 @@ interface paths$1 {
         patch?: never;
         trace?: never;
     };
+    "/v1/auth/access-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Exchange the session cookie for a bearer access token
+         * @description A logged-in (wac_session) user mints a short-lived OAuth-equivalent access token to call the bearer-only operational API (delegated keys, witness writes, chain reads). Keeps those endpoints off the ambient cookie (no CSRF surface). Same claim shape as an OAuth user token.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            accessToken: string;
+                            /** @enum {string} */
+                            tokenType: "Bearer";
+                            expiresIn: number;
+                            expiresAt: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/auth/login": {
         parameters: {
             query?: never;
@@ -10296,14 +10366,6 @@ type SetMemberRoleRequest = Req<'/v1/orgs/me/members/{userId}/role', 'put'>;
 type SetMemberRoleResponse = Res<'/v1/orgs/me/members/{userId}/role', 'put'>;
 type RemoveMemberResponse = Res<'/v1/orgs/me/members/{userId}', 'delete'>;
 type ResendInviteResponse = Res<'/v1/orgs/me/members/{userId}/resend-invite', 'post'>;
-type CreateOrganizationRequest = Req<'/v1/admin/organizations', 'post'>;
-type CreateOrganizationResponse = Res<'/v1/admin/organizations', 'post'>;
-type SetAccountTypeRequest = Req<'/v1/admin/organizations/{id}/account-type', 'patch'>;
-type SetAccountTypeResponse = Res<'/v1/admin/organizations/{id}/account-type', 'patch'>;
-type VerifyOrganizationResponse = Res<'/v1/admin/organizations/{id}/verify', 'patch'>;
-type RotateApiKeyResponse = Res<'/v1/admin/organizations/{id}/rotate-key', 'post'>;
-type AdjustCreditsRequest = Req<'/v1/admin/organizations/{id}/adjust-credits', 'post'>;
-type AdjustCreditsResponse = Res<'/v1/admin/organizations/{id}/adjust-credits', 'post'>;
 type ListDelegatedKeysResponse = Res<'/v1/users/me/delegated-keys', 'get'>;
 type PrepareDelegatedKeyRequest = Req<'/v1/users/me/delegated-keys', 'post'>;
 type PreparedDelegatedKeyResponse = Res<'/v1/users/me/delegated-keys', 'post'>;
@@ -10364,10 +10426,11 @@ type DashboardWitnessesResponse = ChainRes<'/v5/dashboard/witnesses', 'get'>;
  *
  * Covers both accounts (identity / billing / OAuth / delegated keys / witness
  * writes via the metered v5 proxy) and chain-api read surfaces (contract
- * info / witness lookup / wallet balance / dashboards). Three convenience
- * clients layer on top — `WitniumchainClient` (end-user),
- * `WitniumchainOrgClient` (org admin), `WitniumchainAdminClient` (sysadmin) —
- * with helpers for signup, subscriptions, and delegated-key provisioning.
+ * info / witness lookup / wallet balance / dashboards). Two convenience
+ * clients layer on top — `WitniumchainClient` (end-user) and
+ * `WitniumchainOrgClient` (org admin) — with helpers for signup,
+ * subscriptions, and delegated-key provisioning. The sysadmin surface lives in
+ * the separate PRIVATE `@witnium/chain-admin-sdk` package, not here.
  *
  * Stripe surface is intentionally Checkout + Customer Portal ONLY. Witnium is
  * not a marketplace, so there is no Stripe Connect onboarding.
@@ -10379,7 +10442,6 @@ type DashboardWitnessesResponse = ChainRes<'/v5/dashboard/witnesses', 'get'>;
  *   - sessionCookie  — `wac_session` value for browser-cookie routes.
  *   - accessToken    — OAuth Bearer JWT for end-user API.
  *   - orgApiKey      — `wcorg_live_…` for org admin.
- *   - adminToken     — sysadmin token.
  *   - signedRequest  — Ed25519 signer for SDK signed-request routes
  *                      (witnesses propose/sign/finalize/revoke). The SDK
  *                      does the canonical-message construction; you supply
@@ -10505,8 +10567,6 @@ interface WitniumchainClientConfig {
     verifierStorage?: PkceVerifierStorage;
     /** Organisation API key (`wcorg_live_…`). */
     orgApiKey?: string;
-    /** System-admin token (`Authorization: Bearer <ADMIN_TOKEN>`). */
-    adminToken?: string;
     /** Ed25519 signer for SDK signed-request routes (witness write ops). */
     signedRequest?: SignedRequestSigner;
     /** Per-request timeout in milliseconds. Default 30000. */
@@ -10580,6 +10640,8 @@ declare class WitniumchainClient {
     private readonly verifierStorage;
     private discoveryCache;
     private refreshInFlight;
+    private accessTokenFromSession;
+    private sessionExchangeInFlight;
     /** Subscriptions / billing helpers. See {@link Subscriptions}. */
     readonly subscriptions: Subscriptions;
     /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -10629,11 +10691,6 @@ declare class WitniumchainClient {
     getMyOrg(): Promise<PublicOrgResponse>;
     createOrgUser(body: CreateUserRequest): Promise<CreateUserResponse>;
     listOrgUsers(): Promise<ListUsersResponse>;
-    createOrganization(body: CreateOrganizationRequest): Promise<CreateOrganizationResponse>;
-    setOrgAccountType(id: string, body: SetAccountTypeRequest): Promise<SetAccountTypeResponse>;
-    verifyOrganization(id: string): Promise<VerifyOrganizationResponse>;
-    rotateOrgApiKey(id: string): Promise<RotateApiKeyResponse>;
-    adjustOrgCredits(id: string, body: AdjustCreditsRequest): Promise<AdjustCreditsResponse>;
     listDelegatedKeys(query?: {
         contractAddress?: string;
         active?: 'true' | 'false';
@@ -10754,6 +10811,41 @@ declare class WitniumchainClient {
      * instead of retrying with a now-invalid token.
      */
     refreshAccessToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Exchange the logged-in session (the `wac_session` cookie) for a short-lived
+     * bearer access token and cache it as the client's `accessToken`.
+     *
+     * This is the SDK side of the session→token model (accounts'
+     * `POST /v1/auth/access-token`): the dashboard authenticates with the
+     * cookie, but the operational API (delegated keys, witness writes, chain
+     * reads) is bearer-only — no endpoint accepts the ambient cookie, so there's
+     * no CSRF surface even with `SameSite=None`. The minted token is
+     * byte-compatible with an OAuth user token (same signing key, `iss`, `aud`,
+     * scope + org/role/contracts claims), so every `BearerJWT` route accepts it.
+     *
+     * Callers rarely invoke this directly — {@link applyAuth} mints transparently
+     * on the first `BearerJWT` call when no token is set and re-mints on a 401.
+     * It's exposed so a dashboard can pre-warm the token right after login.
+     *
+     * Requires a session: either `sessionCookie` on the constructor (Node) or an
+     * ambient `wac_session` cookie carried by the browser (`credentials:
+     * 'include'`). Throws {@link WitniumchainApiError} (401) when there's no
+     * valid session.
+     */
+    exchangeSessionForToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Best-effort transparent mint for the `BearerJWT` path: if no access token
+     * is cached, try the session exchange (single-flight). Swallows failure so
+     * the caller in {@link applyAuth} surfaces the actionable "no token / no
+     * session" guidance rather than a raw 401 from the exchange endpoint.
+     */
+    private ensureSessionAccessToken;
+    /**
+     * Obtain a fresh access token for a 401-retry, picking the right mechanism:
+     * an OAuth refresh when a refresh credential exists, else a session re-mint
+     * for a session-exchanged token. Returns true when a fresh token is in hand.
+     */
+    private reauthenticateForRetry;
     /**
      * End the OAuth session.
      *
@@ -10968,50 +11060,6 @@ declare class MfaRecoveryCodes {
     regenerate(): Promise<RecoveryCodesRegenerateResponse>;
 }
 
-interface WitniumchainAdminClientConfig {
-    /** Base URL, e.g. `https://auth.witniumchain.com`. Trailing slash optional. */
-    baseUrl: string;
-    /** System-admin token (`Authorization: Bearer <ADMIN_TOKEN>`). */
-    adminToken: string;
-    /** Per-request timeout in milliseconds. Default 30000. */
-    timeout?: number;
-    /** Alternate fetch implementation (e.g. for tests). Default `globalThis.fetch`. */
-    fetch?: typeof fetch;
-}
-type AccountType = 'metered' | 'unlimited';
-declare class WitniumchainAdminClient {
-    private readonly inner;
-    constructor(config: WitniumchainAdminClientConfig);
-    /**
-     * Mint a new organisation. The returned `apiKey` is shown ONCE — the server
-     * only retains its SHA-256 hash. Persist it before the response leaves
-     * scope; there is no recovery path.
-     *
-     * @param body  Organisation seed: name, email, optional accountType and
-     *              signup credit grant, optional skip-email-verification flag.
-     */
-    createOrganization(body: CreateOrganizationRequest): Promise<CreateOrganizationResponse>;
-    /** Flip an org between `metered` (Stripe checkout + credit ledger) and `unlimited` (flat-fee). */
-    setAccountType(orgId: string, accountType: AccountType): Promise<SetAccountTypeResponse>;
-    /** Mark an org's email as verified. Prerequisite for the org to create users. */
-    verifyEmail(orgId: string): Promise<VerifyOrganizationResponse>;
-    /**
-     * Rotate the org's API key. The previous `wcorg_live_…` is invalidated and
-     * the new key is returned ONCE — same one-time-secret semantics as
-     * {@link createOrganization}.
-     */
-    rotateApiKey(orgId: string): Promise<RotateApiKeyResponse>;
-    /**
-     * Apply a signed credit delta to an org's ledger. Positive `delta` grants
-     * credits (goodwill, migration backfill); negative claws them back.
-     * Recorded as `reason: adjustment` with the supplied `note`.
-     *
-     * Use sparingly — this bypasses Stripe and should be auditable from the
-     * `note` alone.
-     */
-    adjustCredits(orgId: string, delta: number, note?: string): Promise<AdjustCreditsResponse>;
-}
-
 type Body<T> = T extends {
     content: {
         'application/json': infer J;
@@ -11078,13 +11126,13 @@ declare class WitniumchainChainAdminClient {
  * Wraps the three `/v1/orgs/me/*` routes that org admins use to read their
  * own org profile and manage their users. This is the client B2B2C apps and
  * customer-admin dashboards consume — auth is the `wcorg_live_…` API key
- * minted via `WitniumchainAdminClient.createOrganization` or returned by
- * a subsequent `rotateApiKey`.
+ * minted by the sysadmin admin SDK or returned by a subsequent `rotateApiKey`.
  *
  * The surface is intentionally minimal — the underlying API only exposes
  * profile read + user create + user list. Anything more powerful (provision
  * credits, change account type, verify email) requires the sysadmin
- * `AdminToken` and therefore lives on `WitniumchainAdminClient`.
+ * `ADMIN_TOKEN` and lives in the PRIVATE `@witnium/chain-admin-sdk` package,
+ * never in this public SDK.
  */
 
 interface WitniumchainOrgClientConfig {
@@ -11202,4 +11250,4 @@ declare function buildRevokeSigningKeyPayload(args: {
     key: string;
 }): string;
 
-export { type AccountResponse, type AccountType, type paths$1 as AccountsPaths, type AddSigningKeyRequest$1 as AddSigningKeyRequest, type AddSigningKeyResponse, type AdjustCreditsRequest, type AdjustCreditsResponse, type BeginOAuthLoginArgs, type BeginOAuthLoginResult, type paths as ChainPaths, type CheckoutRequest, type CheckoutResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type CreateUserResponse, DelegatedKeys, type FinalizeWitnessResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetWitnessResponse, type HealthLiveResponse, type HealthReadyResponse, type InviteMemberRequest, type InviteMemberResponse, type LedgerResponse, type ListDelegatedKeysResponse, type ListOauthSessionsResponse, type ListUsersResponse, type LoginRequest, type LoginResponse, type LogoutResponse, type MembersListResponse, MfaNamespace, MfaRecoveryCodes, MfaTotp, type OAuthTokenSnapshot, OWNER_OP, OauthNamespace, OauthSessions, OrgMembers, OrgUsers, type OwnerOpName, type OwnerSigner, type PauseRequest$1 as PauseRequest, type PauseResponse, type PkceVerifierStorage, type PortalResponse, type PrepareDelegatedKeyRequest, type PreparedDelegatedKeyResponse, type ProposeWitnessRequest, type ProposeWitnessResponse, type ProvisionContractRequest, type ProvisionContractResponse, type ProvisionDelegatedKeyArgs, type ProvisionDelegatedKeyResult, type PublicOrgResponse, type RecoveryCodesRegenerateResponse, type ReissueProvisioningTokenResponse, type RemoveMemberResponse, type ResendInviteResponse, type ResetAccountResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDelegatedKeyResponse, type RevokeSigningKeyRequest$1 as RevokeSigningKeyRequest, type RevokeSigningKeyResponse, type RevokeWitnessRequest, type RevokeWitnessResponse, type RotateApiKeyResponse, type SetAccountTypeRequest, type SetAccountTypeResponse, type SetMemberRoleRequest, type SetMemberRoleResponse, type SignRequest, type SignResponse, type SignWitnessRequest, type SignWitnessResponse, type SignedRequestSigner, SigningKeys, type SignupRequest, type SignupResponse, type SubmitDelegatedKeyRequest, type SubmitDelegatedKeyResponse, Subscriptions, type SuspendMemberResponse, type TotpConfirmRequest, type TotpConfirmResponse, type TotpDisableResponse, type TotpEnrollResponse, type UnpauseRequest, type UnpauseResponse, type VerifyEmailResponse, type VerifyOrganizationResponse, WitniumchainAdminClient, type WitniumchainAdminClientConfig, WitniumchainApiError, WitniumchainChainAdminClient, type WitniumchainChainAdminClientConfig, WitniumchainClient, type WitniumchainClientConfig, WitniumchainOrgClient, type WitniumchainOrgClientConfig, buildAddSigningKeyPayload, buildPausePayload, buildRevokeSigningKeyPayload, buildUnpausePayload, defaultVerifierStorage };
+export { type AccountResponse, type paths$1 as AccountsPaths, type AddSigningKeyRequest$1 as AddSigningKeyRequest, type AddSigningKeyResponse, type BeginOAuthLoginArgs, type BeginOAuthLoginResult, type paths as ChainPaths, type CheckoutRequest, type CheckoutResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateUserRequest, type CreateUserResponse, DelegatedKeys, type FinalizeWitnessResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetWitnessResponse, type HealthLiveResponse, type HealthReadyResponse, type InviteMemberRequest, type InviteMemberResponse, type LedgerResponse, type ListDelegatedKeysResponse, type ListOauthSessionsResponse, type ListUsersResponse, type LoginRequest, type LoginResponse, type LogoutResponse, type MembersListResponse, MfaNamespace, MfaRecoveryCodes, MfaTotp, type OAuthTokenSnapshot, OWNER_OP, OauthNamespace, OauthSessions, OrgMembers, OrgUsers, type OwnerOpName, type OwnerSigner, type PauseRequest$1 as PauseRequest, type PauseResponse, type PkceVerifierStorage, type PortalResponse, type PrepareDelegatedKeyRequest, type PreparedDelegatedKeyResponse, type ProposeWitnessRequest, type ProposeWitnessResponse, type ProvisionContractRequest, type ProvisionContractResponse, type ProvisionDelegatedKeyArgs, type ProvisionDelegatedKeyResult, type PublicOrgResponse, type RecoveryCodesRegenerateResponse, type ReissueProvisioningTokenResponse, type RemoveMemberResponse, type ResendInviteResponse, type ResetAccountResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDelegatedKeyResponse, type RevokeSigningKeyRequest$1 as RevokeSigningKeyRequest, type RevokeSigningKeyResponse, type RevokeWitnessRequest, type RevokeWitnessResponse, type SetMemberRoleRequest, type SetMemberRoleResponse, type SignRequest, type SignResponse, type SignWitnessRequest, type SignWitnessResponse, type SignedRequestSigner, SigningKeys, type SignupRequest, type SignupResponse, type SubmitDelegatedKeyRequest, type SubmitDelegatedKeyResponse, Subscriptions, type SuspendMemberResponse, type TotpConfirmRequest, type TotpConfirmResponse, type TotpDisableResponse, type TotpEnrollResponse, type UnpauseRequest, type UnpauseResponse, type VerifyEmailResponse, WitniumchainApiError, WitniumchainChainAdminClient, type WitniumchainChainAdminClientConfig, WitniumchainClient, type WitniumchainClientConfig, WitniumchainOrgClient, type WitniumchainOrgClientConfig, buildAddSigningKeyPayload, buildPausePayload, buildRevokeSigningKeyPayload, buildUnpausePayload, defaultVerifierStorage };