@hanzo/rooms 0.1.0

package/dist/lib/session.d.ts

@@ -0,0 +1,211 @@
+/**
+ * WHERE THE SESSION IS KEPT, named once.
+ *
+ * The @hanzo/iam SDK owns these keys and publishes no reader a plain module can
+ * call — `getSession()` needs `configureIam()`, and this app configures through
+ * `IamProvider` instead. So the names are restated here, in ONE file, and
+ * everything that needs the bearer asks this.
+ *
+ * That is not a style preference. Four modules restated the name themselves and
+ * every one of them got it wrong — they read `hanzo_access_token` while the SDK
+ * writes `hanzo_iam_access_token`, so invitations, referrals, coding runs and
+ * signed-in telemetry all read null and behaved as if nobody was signed in.
+ * Nothing errored: `bearer()` threw "Sign in to manage invitations" at somebody
+ * who was signed in, which reads as a permissions problem rather than a typo.
+ * Two derivations of one name never agree; this is the one derivation.
+ */
+/**
+ * The access token, or null.
+ *
+ * Guarded because storage THROWS rather than answering null in a browser that
+ * refuses it, and a caller reaching for the bearer is usually about to make a
+ * request — one that should fail as unauthenticated, not as an exception.
+ */
+export declare function bearer(): string | null;
+/**
+ * Whether the stored access token is live: present, and not past the expiry the
+ * SDK wrote beside it — the SDK's own fast path (`IAM#getValidAccessToken`)
+ * without the refresh, which is a request and cannot be waited for here. No
+ * expiry reads as live, as it does in the SDK.
+ */
+export declare function live(): boolean;
+/** The attribute on `<html>` that says `/` is showing the app, not the landing. */
+export declare const APP = "data-app";
+/** Whether `search` names a place in the app. */
+export declare const place: (search: string) => boolean;
+/**
+ * `live()`, and a place in the app, as the script `/` runs as the first child
+ * of its landing (app/_apex.tsx `[data-landing]`), before the rest of the
+ * landing is parsed (app/page.tsx). Either marks the document with `APP` and
+ * takes the landing off the page at once: a signed-in reader is never shown the
+ * pitch while the app loads, and a reader on their way to sign in to a place is
+ * not shown it while they leave. Same keys, same test. An inline style, because
+ * this is decided before any stylesheet or component has run.
+ */
+export declare const BOOT: string;
+/**
+ * Whether this tab may still ask: a person's browser, and not asked in this tab
+ * yet. A browser that refuses storage cannot remember having asked, so it never
+ * asks.
+ */
+export declare function unasked(): boolean;
+/** Spend this tab's ask: it is written down before it is made, so it is made once. */
+export declare function asked(): void;
+/**
+ * Whether the browser holds an existing session (stored token, JWT subject,
+ * or migration candidate).
+ *
+ * Guarded against storage exceptions. Used across workspace and marketing
+ * headers so a signed-in person never sees "Sign in".
+ */
+export declare function hasSession(): boolean;
+/**
+ * Carry a session across the move from per-tab storage to per-origin.
+ *
+ * The session used to be held in `sessionStorage`, which is why it did not
+ * survive closing a tab. It is `localStorage` now — but everyone already signed
+ * in was signed in THERE, and the new build looks HERE, so the fix for "I have
+ * to sign in again" would itself have signed everybody out one last time.
+ *
+ * The old store is read once and its keys moved over. After that this does
+ * nothing, because there is nothing left to find: a migration, not a fallback,
+ * and a fallback is what would keep two answers about who is signed in alive.
+ *
+ * ONLY WHEN THE NEW STORE IS EMPTY. A session established since the move is the
+ * current one, and a stale per-tab copy must never overwrite it.
+ */
+export declare function carry(): void;
+/**
+ * The subject the stored access token names, or undefined.
+ *
+ * Read off the claim rather than waited for from userinfo, because that is
+ * what makes `own` runnable BEFORE anything else reads storage: the token is
+ * in place from the first line of the first script, and the SDK's own fast
+ * path judges a session the same way. Expiry is not consulted — a stale
+ * token still says whose browser this is, and the SDK either refreshes it or
+ * clears it, at which point the answer changes here too.
+ */
+export declare function subject(): string | undefined;
+/**
+ * Bind everything this site keeps in the browser to ONE person.
+ *
+ * Every `hanzo*` key — conversations, contacts, the calendar, the board, the
+ * agent's persona, the chat's history, the SDK's current org — is written per
+ * browser and would be read by whoever is signed in next. So the subject is
+ * recorded beside them, and when a different subject arrives (or nobody: a
+ * sign-out) the last person's keys are removed before anything reads them.
+ * The SDK's `hanzo_iam_*` keys are the arriving session itself and stay —
+ * except the org and project it last selected, which are the last person's.
+ *
+ * Same subject, no work. Called synchronously where the providers mount, so
+ * a page's first read of storage already sees a browser that is the reader's.
+ */
+export declare function own(sub: string | undefined): void;
+/**
+ * Follow the session every tab of this site shares.
+ *
+ * The SDK in each tab keeps its own copy of who is signed in and is told
+ * nothing when another tab changes the store. A sign-out there empties the
+ * tokens, and a tab that did not hear it goes on drawing the person it was
+ * opened for while every call it makes carries `X-Org-Id` and no bearer, which
+ * the platform answers as nobody (`a validated principal is required`).
+ *
+ * `moved` runs when the stored access token stops naming `was` — removed, or
+ * naming someone else; a cleared store (`key` null) is read the same way — and
+ * when the organization a SuperAdmin stepped into (`assumed`) changes, because
+ * the person is the same and every request's scope is not. Any other token for
+ * the same subject is not a move: that is a refresh in another tab, and
+ * `bearer()` reads it at call time. A tab on the sign-in callback is finishing
+ * its own sign-in and is left to it.
+ *
+ * When the store is left with nobody, the silent ask is marked spent in this
+ * tab before `moved` runs: the sign-out that emptied it may still be on its way
+ * to IAM, and an ask arriving first would be answered from the session being
+ * ended and sign this tab straight back in. The reader signs in again from the
+ * form. Returns the unsubscribe.
+ */
+export declare function follow(was: string | undefined, moved: () => void): () => void;
+/**
+ * The organizations the token says this person belongs to, home first.
+ * Empty for an account that has not made one: the SDK's own list falls back to
+ * the `owner` claim, which is the application's org and nobody's to work in.
+ */
+export declare function orgs(): string[];
+/**
+ * The reader's role in one organization as IAM signed it into the token's `orgs`
+ * claim — owner, admin or member — or null where the token names no such org.
+ * It is the role in THAT org only (HIP-0527: org admin is scoped to its org), so
+ * it says nothing about any other org and nothing about SuperAdmin.
+ */
+export declare function role(o: string | null): string | null;
+/**
+ * Who the token names — its display name and email — or null. The IAM user says
+ * the same once userinfo answers; this is the answer before it, so a signed-in
+ * reader is never drawn as a stranger while it is asked.
+ */
+export declare function named(): {
+    name: string;
+    email: string;
+} | null;
+/**
+ * The reader's account as IAM keys a membership: `<home org>/<username>`, or null.
+ * The token's `name` is the username and its `orgs` claim lists the home org first.
+ */
+export declare function me(): string | null;
+/** The organization this browser works in: the SDK's selection, when it is one of the token's. */
+export declare function org(): string | null;
+/** The headers that scope a request to the signed-in person and their organization. */
+export declare function scope(): Record<string, string>;
+/**
+ * Expire the access token so the next load mints one carrying the account's
+ * current claims — after it joins an organization. The token itself stays,
+ * because it is what names the person: removing it would read as a sign-out
+ * and `own()` would empty everything the person just chose. The SDK sees an
+ * expired token and refreshes on the refresh token.
+ */
+export declare function renew(): void;
+/** Fired on `window` when the organization this browser works in changes. */
+export declare const ORG = "hanzo:org";
+/** This person picked an organization in this browser. `own()` clears it with the person. */
+export declare const PICKED = "hanzo:org:picked";
+/**
+ * Work in this organization from now on: the SDK's selection, noted as picked
+ * and announced. Noted here, so a choice made anywhere — the rooms' gate, the
+ * app's account menu — is one the gate does not ask for again.
+ */
+export declare function pick(o: string): void;
+/** The reserved org whose own people are the platform's operators. */
+export declare const ADMIN_ORG = "admin";
+/**
+ * Whether the signed-in person is a SUPERADMIN, as IAM signs it: the org of the
+ * person's own row — the first entry of the token's `orgs`, which IAM always puts
+ * first (hanzoai/iam internal/store/membership.go `MemberOrgRefs`) — is the
+ * reserved `admin` org. It is the equality IAM decides `assume` and the
+ * organization list on (pkg/schema/user.go `SuperAdmin`) and cloud's `Super`.
+ * Not the `owner` claim: a sign-in token carries the APPLICATION's org there. A
+ * membership of `admin` is not it either, and neither is being an org's admin.
+ * It decides only what is drawn: IAM refuses everyone else the list of every
+ * organization and the step into one.
+ */
+export declare function superAdmin(): boolean;
+/** The organization a SuperAdmin stepped into through IAM, from the token's `assumed` claim, or null. */
+export declare function assumed(): string | null;
+/**
+ * Step into an organization as its support, or step back out (`org` null).
+ *
+ * IAM does the whole act: `POST /v1/iam/assume {org}` answers the same person's
+ * token re-scoped to that organization — `assumed` names it and `orgs` gains it —
+ * and records the step in that organization's audit log; `POST /v1/iam/release`
+ * answers the token with nothing assumed and records that too
+ * (hanzoai/iam internal/oidc/masquerade.go). The answer is kept where the SDK
+ * keeps the session, with its own expiry, so every request made from here on
+ * carries it and the SDK's next refresh ends support mode by itself. The page
+ * reloads so every room reads under it.
+ */
+export declare function support(org: string | null): Promise<void>;
+/**
+ * Leave support mode when IAM cannot answer the step out: the stored token is
+ * marked spent, so the SDK's refresh — which mints from the person's own grant
+ * and assumes nothing — replaces it on the reload.
+ */
+export declare function abandon(): void;