@xenosystem/blocks 0.6.0 → 0.7.0

package/dist/auth/index.d.ts

@@ -1,8 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { PanelModule, PanelManifest } from '@xenosystem/panel-sdk';
-import { XenoAccountStatus, XenoAccountIdentity, XenoAccountActionKind } from '@xenosystem/panel-account';
-export * from '@xenosystem/panel-account';
 import { BlockDeclaration } from '@xenosystem/block-sdk';
 
 interface CreateAuthGatePanelOptions {
@@ -22,6 +20,205 @@ declare const AUTH_GATE_PANEL_ID = "xeno.core.auth-gate";
  */
 declare const authGateManifest: PanelManifest;
 
+/**
+ * The `xeno.core.account` contract.
+ *
+ * ## 🔴 What this panel must NOT do, per `XENO AUTH - SPEC.md`
+ *
+ * A naive account panel violates the locked auth spec in four separate ways. Each is prevented
+ * structurally here, not by convention:
+ *
+ * | Locked rule | The naive mistake | How this contract prevents it |
+ * |---|---|---|
+ * | **L9** — refresh tokens live ONLY in the OS keystore; `~/.xeno/*` holds no secrets; **never** `localStorage` | Persisting a session or token through `serialize()`. The panel's ONE capability is `storage.local`, which is *exactly* the store L9 forbids for a token. | **No token type exists.** `XenoAccountIdentity` has no field a token could occupy, and `serialize()` returns view preferences only. What the panel never receives, it cannot persist. |
+ * | **L10** — the real gate is server-side; client entitlement checks are "legitimacy + friction", never a security boundary | Gating a feature locally on `plan.tier`. | `XenoEntitlement` is explicitly **display-only** and documented as such. The panel exposes no "may I?" predicate for anyone to mistake for a gate. |
+ * | **L12** — step-up re-auth for money/account (plan cancel, account delete, logout-everywhere, payout change) must be a **fresh interactive** auth the broker cannot satisfy silently | Emitting `signOut` or `cancelPlan` as an ordinary intent and rendering success. | Sensitive actions carry `stepUp: true` on the intent, and the panel **never renders a result** — it waits for the host to push new state. |
+ * | **L5** — Hub is the preferred broker, **never a hard dependency**; every product must authenticate with Hub uninstalled | Assuming a broker-supplied identity and rendering nothing without one. | `signedOut` is a first-class, fully-rendered state with its own action. The panel neither knows nor asks whether a broker exists. |
+ *
+ * The panel holds **no network capability** — the same posture as the rest of the family. Identity,
+ * plan, credits and ledger are **host-pushed state**.
+ *
+ * @module
+ */
+/** Who is signed in. **Carries no token, by construction.** */
+interface XenoAccountIdentity {
+    /** The OIDC `sub`. An opaque identifier, not a secret. */
+    sub: string;
+    /** Display name. */
+    name?: string;
+    /** Email, for display. */
+    email?: string;
+    /** Avatar URL. */
+    avatarUrl?: string;
+}
+/** Plan tier. Display only — see L10 above. */
+interface XenoAccountPlan {
+    /** Stable id (`'free'`, `'pro'`, `'team'`). */
+    id: string;
+    /** Display name. */
+    label: string;
+    /** Epoch ms the current period ends. */
+    renewsAt?: number;
+    /** The plan is set to lapse rather than renew. */
+    cancelAtPeriodEnd?: boolean;
+    /** Seats held, for a team plan. */
+    seats?: {
+        used: number;
+        total: number;
+    };
+}
+/**
+ * A credit balance.
+ *
+ * **`asOf` is mandatory.** A balance is a number that goes out of date the moment anything runs, and
+ * a stale one rendered as fresh is worse than no balance at all — a user acts on it. The view must
+ * show the age or show a loading state; there is no third option, which is why the field cannot be
+ * omitted.
+ */
+interface XenoAccountCredits {
+    /** Remaining credits. */
+    balance: number;
+    /** Epoch ms this balance was true. **Mandatory.** */
+    asOf: number;
+    /** Granted this period, when the host tracks it. */
+    included?: number;
+    /** Consumed this period. */
+    used?: number;
+    /** Epoch ms the allowance resets. */
+    resetsAt?: number;
+    /** Currency-style unit label (`'credits'`, `'tokens'`). */
+    unit?: string;
+}
+/** One ledger entry. */
+interface XenoLedgerEntry {
+    /** Stable id. */
+    id: string;
+    /** Epoch ms. */
+    ts: number;
+    /** What happened, in the host's words. */
+    description: string;
+    /** Signed: negative is a spend, positive a grant or purchase. */
+    amount: number;
+    /** Which product or surface spent it. */
+    source?: string;
+    /** Balance immediately after, when the host knows it. */
+    balanceAfter?: number;
+}
+/** An append-oriented ledger update — the same discipline as runs and console. */
+interface XenoLedgerDelta {
+    rev?: number;
+    append?: XenoLedgerEntry[];
+    replace?: XenoLedgerEntry[];
+    clear?: boolean;
+    /** More pages exist before the oldest held entry. */
+    hasMore?: boolean;
+}
+/**
+ * An entitlement, for DISPLAY.
+ *
+ * **Not a gate.** L10: the only unbreakable enforcement is `api.xenostudio.ai` validating the token
+ * and debiting the ledger. Rendering a lock icon is friction and honesty; it is not security, and
+ * nothing here should be mistaken for a permission check.
+ */
+interface XenoEntitlement {
+    id: string;
+    label: string;
+    /** Whether the host says this plan includes it. */
+    included: boolean;
+    /** Host-authored explanation of what unlocks it. */
+    detail?: string;
+}
+/** Session lifecycle. */
+type XenoAccountStatus = 'unknown' | 'signedOut' | 'signedIn'
+/** A silent refresh is in flight. Balance and plan may be stale. */
+ | 'refreshing'
+/** The session expired and interactive sign-in is required. */
+ | 'expired'
+/** The host could not reach the origin. Cached state may still be shown, honestly. */
+ | 'offline';
+/** Everything the host pushes. */
+interface XenoAccountState {
+    status: XenoAccountStatus;
+    identity?: XenoAccountIdentity;
+    plan?: XenoAccountPlan;
+    credits?: XenoAccountCredits;
+    entitlements?: XenoEntitlement[];
+    /** Host-authored message for the current status, rendered verbatim. */
+    message?: string;
+    /**
+     * The active seat, when the host manages several.
+     *
+     * Per L6 there is no shared multi-reader credential; a seat switch is a host flow, not a token
+     * swap the panel performs.
+     */
+    seatId?: string;
+    /** Seats the user may switch to. */
+    seats?: {
+        id: string;
+        label: string;
+        active: boolean;
+    }[];
+}
+/** Actions the panel asks for. **Every one is an intent; the host runs the flow.** */
+type XenoAccountActionKind = 'signIn' | 'signOut' | 'purchase' | 'manageBilling' | 'switchSeat' | 'refresh';
+/** An account intent. */
+interface XenoAccountAction {
+    kind: XenoAccountActionKind;
+    /** For `switchSeat`. */
+    seatId?: string;
+    /** For `purchase` — a host-defined product/pack id. */
+    productId?: string;
+    /**
+     * **L12**: this action needs a FRESH interactive re-auth, which the broker must not satisfy
+     * silently. The panel flags it; the host enforces it.
+     */
+    stepUp?: boolean;
+}
+/**
+ * Actions that require step-up re-auth per `XENO AUTH - SPEC.md` L12.
+ *
+ * Irreversible or money-adjacent operations. `manageBilling` is here because it is the door to plan
+ * cancellation and payout changes, both named in L12.
+ */
+declare const STEP_UP_ACTIONS: ReadonlySet<XenoAccountActionKind>;
+/** The panel's serialized state. **No identity, no session, no balance — see L9.** */
+interface AccountPanelState {
+    /** Whether the ledger section is expanded. A view preference and nothing more. */
+    ledgerExpanded: boolean;
+}
+/** What the controller exposes to its view. */
+interface AccountViewState {
+    status: XenoAccountStatus;
+    identity: XenoAccountIdentity | null;
+    plan: XenoAccountPlan | null;
+    credits: XenoAccountCredits | null;
+    entitlements: XenoEntitlement[];
+    seats: NonNullable<XenoAccountState['seats']>;
+    message: string | null;
+    ledger: XenoLedgerEntry[];
+    ledgerHasMore: boolean;
+    ledgerExpanded: boolean;
+    /**
+     * Age of the balance in ms, or `null` when there is none.
+     *
+     * The view MUST surface this (or a loading state) rather than rendering a number as though it
+     * were current.
+     */
+    creditsAgeMs: number | null;
+    /** The balance is older than the staleness threshold. */
+    creditsStale: boolean;
+}
+/** Is a user signed in right now? */
+declare function isSignedIn(status: XenoAccountStatus): boolean;
+/** Does this action need a fresh interactive auth (L12)? */
+declare function requiresStepUp(kind: XenoAccountActionKind): boolean;
+/** Age of a balance in ms. */
+declare function creditsAge(credits: XenoAccountCredits | undefined, now: number): number | null;
+/** Format a signed ledger amount with an explicit sign. */
+declare function formatAmount(amount: number, unit?: string): string;
+/** Format a balance age compactly. */
+declare function formatAge(ms: number): string;
+
 /**
  * `xeno.core.auth-gate` — the door in front of a XENO product.
  *
@@ -219,4 +416,203 @@ interface MountedXenoAuthGate {
 }
 declare function mountXenoAuthGate(root: HTMLElement, options: MountXenoAuthGateOptions): MountedXenoAuthGate;
 
-export { AUTH_GATE_DECLARATION, AUTH_GATE_INITIAL, AUTH_GATE_PANEL_ID, type AuthGateAction, AuthGateController, type AuthGateHostBridge, AuthGateView$1 as AuthGateView, type AuthGateView as AuthGateViewModel, type AuthGateViewProps, BEHAVIOURS, type CreateAuthGatePanelOptions, type MountXenoAuthGateOptions, type MountedXenoAuthGate, PHASE_INTENTS, type XenoAuthGateBridge, type XenoAuthGateIntent, type XenoAuthGateIntentKind, type XenoAuthGatePhase, type XenoAuthGateState, type XenoLicenceState, authGateManifest, authGatePanel, authGateView, createAuthGatePanel, deriveAuthGatePhase, formatSince, hostContradiction, intentOffered, mountXenoAuthGate, plateCopy };
+/**
+ * The Account controller.
+ *
+ * Everything it holds arrives from the host. **The panel never fetches**: it has no network
+ * capability, no origin, no token, and no knowledge of whether a broker exists. It renders what it
+ * was pushed, timestamps it honestly, and emits intents.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface AccountHostBridge {
+    emit(portId: string, value: unknown): void;
+    now?: () => number;
+}
+/** Construction options. */
+interface AccountControllerOptions {
+    host: AccountHostBridge;
+    /** ms after which a balance is called stale. Default 60 000. */
+    staleAfterMs?: number;
+    /** Ledger entries retained. Default 500. */
+    maxLedger?: number;
+}
+/** The Account panel controller. */
+declare class AccountController {
+    private readonly host;
+    private readonly now;
+    private readonly staleAfterMs;
+    private readonly maxLedger;
+    private account;
+    private ledger;
+    private ledgerHasMore;
+    private ledgerRev;
+    private ledgerExpanded;
+    private readonly listeners;
+    private snapshot;
+    constructor(options: AccountControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => AccountViewState;
+    private notify;
+    /**
+     * Replace the account state.
+     *
+     * The host is authoritative. The panel does not merge cleverly, does not keep a "better" older
+     * value, and does not infer a status the host did not send — a panel that second-guesses its host
+     * is a second source of truth about who is signed in.
+     *
+     * @param next - The new state.
+     */
+    setAccount(next: XenoAccountState): void;
+    /**
+     * A partial update, for hosts that push only what changed.
+     *
+     * `credits` is replaced wholesale rather than field-merged: a balance and its `asOf` are one fact,
+     * and merging a new number onto an old timestamp manufactures a lie.
+     *
+     * @param patch - Fields to overwrite.
+     */
+    patchAccount(patch: Partial<XenoAccountState>): void;
+    /** Set the session status alone. */
+    setStatus(status: XenoAccountStatus, message?: string): void;
+    /**
+     * Apply a ledger delta.
+     *
+     * Append-oriented, with `rev` gating out-of-order deliveries — the same discipline as runs and
+     * console.
+     *
+     * @param delta - The update.
+     * @returns Whether it was applied.
+     */
+    applyLedger(delta: XenoLedgerDelta): boolean;
+    /**
+     * Re-evaluate the balance's age.
+     *
+     * `getState` memoizes — it must, or `useSyncExternalStore` re-renders forever — which means the
+     * age would otherwise freeze at the moment of the last push, and a balance would sit on screen
+     * reading "as of 2s ago" for an hour. That is precisely the stale-as-fresh failure `asOf` exists
+     * to prevent, reintroduced by a caching bug.
+     *
+     * So time is an INPUT here, and the panel drives this on an interval. Notifying only when the
+     * rendered age actually changes keeps it off the re-render hot path: a one-second tick that
+     * re-renders once per second is honest; one that re-renders sixty times is waste.
+     *
+     * @returns Whether anything the view shows changed.
+     */
+    tick(): boolean;
+    /** Expand or collapse the ledger. A view preference. */
+    setLedgerExpanded(expanded: boolean): void;
+    /**
+     * Ask the host to do something.
+     *
+     * **The panel never renders the result.** It does not flip to `signedOut` because the user
+     * clicked Sign out, and it does not add credits because the user clicked Purchase. It emits, and
+     * waits to be told — the same intents-only doctrine the rest of the family follows, and the only
+     * shape compatible with `XENO AUTH - SPEC.md` L12, where a sensitive action may be REFUSED at the
+     * step-up prompt after the click.
+     *
+     * @param kind - What to ask for.
+     * @param extra - `seatId` or `productId`.
+     * @returns The emitted action.
+     */
+    request(kind: XenoAccountActionKind, extra?: Omit<XenoAccountAction, 'kind' | 'stepUp'>): XenoAccountAction;
+    /** Ask the host to re-read the balance. Cheap, idempotent, no step-up. */
+    refresh(): XenoAccountAction;
+    /**
+     * Serialize.
+     *
+     * **View preferences only.** No identity, no plan, no balance, no token.
+     *
+     * `XENO AUTH - SPEC.md` L9 forbids a refresh token in `localStorage` or `~/.xeno/*`, and this
+     * panel's one capability is `storage.local` — the very store L9 names. Persisting a balance would
+     * also reintroduce the stale-as-fresh problem `asOf` exists to solve: a number restored from disk
+     * has no honest timestamp.
+     */
+    serialize(): {
+        ledgerExpanded: boolean;
+    };
+    /** Restore view preferences. */
+    deserialize(state: unknown): void;
+    /** Tear down. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface AccountRenderContext {
+    controller: AccountController;
+    config: {
+        showLedger: boolean;
+        showEntitlements: boolean;
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createAccountPanel}. */
+interface CreateAccountPanelOptions {
+    /** Override the view. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: AccountRenderContext) => () => void;
+}
+/**
+ * Build the Account panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createAccountPanel(options?: CreateAccountPanelOptions): PanelModule;
+/** The default Account panel module — view already wired. Register THIS. */
+declare const accountPanel: PanelModule;
+
+/**
+ * The `xeno.core.account` manifest.
+ *
+ * Capabilities: `storage.local` only — **no `net.fetch`**. That is not an oversight. Identity, plan,
+ * credits and ledger are host-pushed; a panel that could reach the origin itself would need a token,
+ * and a token is exactly what `XENO AUTH - SPEC.md` L9 says must never live where this panel can
+ * reach.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const ACCOUNT_PANEL_ID = "xeno.core.account";
+/** The `xeno.core.account` manifest. */
+declare const accountManifest: PanelManifest;
+
+/**
+ * The Account panel view.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure `@xenosystem/workbench/primitives.css` is
+ * present.
+ *
+ * Three deliberate absences, each traceable to `XENO AUTH - SPEC.md`:
+ *
+ * - **No secret-reveal affordance.** `xeno-hub` has one (a masked API key with an eye toggle). It is
+ *   deliberately not lifted: a shared panel that can render a secret is a shared panel that can leak
+ *   one into a screenshot, a screen share, or a `serialize()`. L9 keeps secrets in the keystore, and
+ *   the surest way to honour that is to have nothing to reveal.
+ * - **No optimistic success.** Clicking Sign out does not sign you out on screen. L12 says a
+ *   sensitive action needs a fresh interactive re-auth that the user may cancel or fail; a view that
+ *   had already cleared the name would be lying about state it does not own.
+ * - **No local gate.** Entitlements render as facts, never as enforcement (L10).
+ *
+ * @module
+ */
+
+/** Props for {@link AccountPanelView}. */
+interface AccountPanelViewProps {
+    controller: AccountController;
+    showLedger?: boolean;
+    showEntitlements?: boolean;
+    emptyHint?: string;
+}
+/** The Account panel view. */
+declare function AccountPanelView({ controller, showLedger, showEntitlements, emptyHint, }: AccountPanelViewProps): ReactNode;
+
+export { ACCOUNT_PANEL_ID, AUTH_GATE_DECLARATION, AUTH_GATE_INITIAL, AUTH_GATE_PANEL_ID, AccountController, type AccountControllerOptions, type AccountHostBridge, type AccountPanelState, AccountPanelView, type AccountPanelViewProps, type AccountRenderContext, type AccountViewState, type AuthGateAction, AuthGateController, type AuthGateHostBridge, AuthGateView$1 as AuthGateView, type AuthGateView as AuthGateViewModel, type AuthGateViewProps, BEHAVIOURS, type CreateAccountPanelOptions, type CreateAuthGatePanelOptions, type MountXenoAuthGateOptions, type MountedXenoAuthGate, PHASE_INTENTS, STEP_UP_ACTIONS, type XenoAccountAction, type XenoAccountActionKind, type XenoAccountCredits, type XenoAccountIdentity, type XenoAccountPlan, type XenoAccountState, type XenoAccountStatus, type XenoAuthGateBridge, type XenoAuthGateIntent, type XenoAuthGateIntentKind, type XenoAuthGatePhase, type XenoAuthGateState, type XenoEntitlement, type XenoLedgerDelta, type XenoLedgerEntry, type XenoLicenceState, accountManifest, accountPanel, authGateManifest, authGatePanel, authGateView, createAccountPanel, createAuthGatePanel, creditsAge, deriveAuthGatePhase, formatAge, formatAmount, formatSince, hostContradiction, intentOffered, isSignedIn, mountXenoAuthGate, plateCopy, requiresStepUp };