@bounded-sh/core 0.0.100 → 0.0.101

package/dist/client/app-token.d.ts

@@ -0,0 +1,77 @@
+/** A minted child-app credential and the moment it stops being usable. */
+export interface AppToken {
+    /** The bare id token to send as `Authorization: Bearer <token>`. */
+    token: string;
+    /** Epoch milliseconds at which the token expires. */
+    expiresAtMs: number;
+    /** The child app the token is pinned to. */
+    appId: string;
+}
+/** Why an exchange stopped trying. Recorded, never retried past this point. */
+export interface AppTokenGiveUp {
+    appId: string;
+    /** HTTP status of the last attempt, or null for a transport failure. */
+    status: number | null;
+    /** Machine-readable reason: the issuer's `error` field where it sent one. */
+    reason: string;
+    attempts: number;
+}
+export interface ExchangeAppTokenOptions {
+    /**
+     * Origin of the Bounded Auth issuer that serves `/app-token/exchange` - the
+     * resolved `humanAuthApiUrl` for your network. A path suffix is tolerated.
+     */
+    authApiUrl: string;
+    /** The child app to mint a token for. */
+    appId: string;
+    /** The signed-in PARENT app's id token (e.g. the venue session's). */
+    parentToken: string;
+    /** HTTP attempts, including the first. Default 3, clamped to 1..5. */
+    maxAttempts?: number;
+    /** Called once when an exchange stops trying. Defaults to a console warning. */
+    onGiveUp?: (info: AppTokenGiveUp) => void;
+    /** Test seam; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** Thrown when an exchange stops trying. `giveUp` carries the recorded reason. */
+export declare class AppTokenExchangeError extends Error {
+    readonly giveUp: AppTokenGiveUp;
+    constructor(giveUp: AppTokenGiveUp);
+}
+/**
+ * Get a child-app id token for the human the parent token belongs to, from cache
+ * when one is still comfortably fresh and otherwise by exchanging once.
+ *
+ * Concurrent callers for the same (parent credential, appId) share one exchange.
+ * On give-up this rejects with {@link AppTokenExchangeError} and caches nothing.
+ */
+export declare function exchangeAppToken(options: ExchangeAppTokenOptions): Promise<AppToken>;
+/**
+ * Drop cached child-app tokens. Call this on sign-out; an identity change needs
+ * no call, because the cache key is the exact parent credential.
+ *
+ * With no argument every entry goes. `appId` narrows to one child app, and
+ * `parentToken` narrows to one session's entries.
+ */
+export declare function clearAppTokenCache(scope?: {
+    appId?: string;
+    parentToken?: string;
+}): void;
+export interface AppTokenAuthHeadersOptions extends Omit<ExchangeAppTokenOptions, 'parentToken'> {
+    /**
+     * The CURRENT parent-app credential, read on every call so a refreshed session
+     * is picked up and a signed-out one degrades the instance to anonymous.
+     * Return the bare id token, or null/undefined when signed out.
+     */
+    parentToken: () => string | null | undefined | Promise<string | null | undefined>;
+}
+/**
+ * Build the `getAuthHeaders` a scoped `createClient({ appId, getAuthHeaders })`
+ * instance authenticates with, backed by {@link exchangeAppToken}.
+ *
+ * Signed out (`parentToken()` yields nothing) returns NO headers, which leaves
+ * the scoped instance anonymous - the public read lane - instead of failing. A
+ * give-up on the exchange itself rejects, so a broken exchange surfaces as an
+ * error rather than as silently unauthenticated reads.
+ */
+export declare function createAppTokenAuthHeaders(options: AppTokenAuthHeadersOptions): () => Promise<Record<string, string>>;

package/dist/client/create-client.d.ts

@@ -14,24 +14,58 @@
  * per-subscription override channel, plus the websocket layer already keying
  * connections by appId.
  *
- * ## v1 scope: read-only, unauthenticated
+ * ## Anonymous by default, authenticated with `getAuthHeaders`
  *
- * A scoped instance is UNAUTHENTICATED. It sends no auth, never reads or
- * refreshes the global session, and connects to its app's realtime endpoint
- * anonymously. It is therefore only useful against collections a Bounded app
- * exposes with a public read rule (`read: true`) - private/per-user reads will
- * be denied by the target app's policy, exactly as an anonymous caller would be.
+ * With no `getAuthHeaders`, a scoped instance is UNAUTHENTICATED. It sends no
+ * auth, never reads or refreshes the global session, and connects to its app's
+ * realtime endpoint anonymously. It is therefore only useful against collections
+ * a Bounded app exposes with a public read rule (`read: true`) - private/per-user
+ * reads will be denied by the target app's policy, exactly as an anonymous caller
+ * would be.
+ *
+ * Supply `getAuthHeaders` and the instance authenticates AS THAT CREDENTIAL, on
+ * both transports, with nothing shared with any other principal:
+ *   - HTTP sends exactly the headers the provider returns, alongside this
+ *     instance's `X-App-Id`. The provider is the SOLE auth source: the ambient
+ *     global session is neither read nor refreshed nor cleared, and the read
+ *     cache is keyed by the provider's own opaque credential.
+ *   - The websocket gets its OWN connection, keyed by that credential
+ *     (`principalKey`/`principalToken`), so it never shares a socket, an auth
+ *     frame or cached data with the global client or with an anonymous scoped
+ *     instance for the same appId.
+ *   - No per-instance session is ever persisted. The global session store (which
+ *     deletes a stored session whose appId differs from the global config's) is
+ *     only reachable through the global session manager, and a per-instance
+ *     provider never calls into it.
+ *   - A provider that returns no credential leaves the instance ANONYMOUS for
+ *     that call rather than failing it, so a signed-out page degrades to the
+ *     public read lane. An already-authenticated socket is never silently
+ *     downgraded: it keeps failing closed on a credential that stops resolving.
  *
  * Writes and any auth-requiring surface are NOT supported on a scoped instance
- * and throw a clear error. Per-instance authentication is a planned follow-up.
+ * and throw a clear error, with or without a credential.
  */
 import { type GetOptions, type SearchOptions, type CountOptions, type AggregateOptions, type QueryAggregateOptions, type RunQueryOptions, type AggregateOperation, type AggregateResult, type AggregateRow, type AggregateSpec, type GetManyResult, type RequestOverrides } from './operations';
 import { type ClientConfig } from './config';
 import type { SubscriptionOptions } from '../types';
+/**
+ * Resolve the auth headers a scoped instance authenticates with. Called per
+ * request and per subscribe, so a rotated credential is picked up without
+ * recreating the client.
+ *
+ * Return `{ Authorization: 'Bearer <idToken>' }` for the app this instance is
+ * bound to - typically from `createAppTokenAuthHeaders`, which exchanges the
+ * signed-in parent app's session for a child-app token. Return `{}` (or null)
+ * when there is no credential: the instance stays anonymous for that call.
+ */
+export type ScopedAuthHeadersProvider = () => Record<string, string> | null | undefined | Promise<Record<string, string> | null | undefined>;
 /** Config accepted by {@link createClient}. Only `appId` is required; `network`
- *  (or explicit endpoint fields) selects the target Bounded backend. */
+ *  (or explicit endpoint fields) selects the target Bounded backend. Supply
+ *  `getAuthHeaders` to make the instance authenticated instead of anonymous. */
 export type CreateClientConfig = Partial<ClientConfig> & {
     appId: string;
+    /** Per-instance credential source. See {@link ScopedAuthHeadersProvider}. */
+    getAuthHeaders?: ScopedAuthHeadersProvider;
 };
 /**
  * A read-only client scoped to a single Bounded app, isolated from the global
@@ -40,6 +74,8 @@ export type CreateClientConfig = Partial<ClientConfig> & {
 export interface BoundedClient {
     /** The app id this instance is bound to. */
     readonly appId: string;
+    /** True when this instance was given a `getAuthHeaders` credential source. */
+    readonly authenticated: boolean;
     /** A snapshot of this instance's fully-resolved config (endpoints + appId). */
     getConfig(): ClientConfig;
     /** Read a document or collection. See the global `get`. */
@@ -68,36 +104,52 @@ export interface BoundedClient {
     }[], opts?: RunQueryOptions): Promise<any[]>;
     /**
      * Subscribe to realtime updates for a path on THIS app's realtime endpoint.
-     * Anonymous (read-only): the collection must be publicly readable. Returns an
-     * unsubscribe function. Subscriptions on this instance are fully independent
-     * of the global client and of any other scoped instance.
+     * Authenticated when the instance has a credential (its own socket, keyed by
+     * that credential), anonymous otherwise - in which case the collection must be
+     * publicly readable. Returns an unsubscribe function. Subscriptions on this
+     * instance are fully independent of the global client and of any other scoped
+     * instance.
      */
     subscribe(path: string, options: SubscriptionOptions | ((data: any) => void)): Promise<() => Promise<void>>;
-    /** Not supported on a read-only scoped instance - always throws {@link ScopedClientReadOnlyError}. */
+    /** Not supported on a scoped instance - always throws {@link ScopedClientReadOnlyError}. */
     set(path: string, document: any): Promise<never>;
-    /** Not supported on a read-only scoped instance - always throws {@link ScopedClientReadOnlyError}. */
+    /** Not supported on a scoped instance - always throws {@link ScopedClientReadOnlyError}. */
     setMany(many: {
         path: string;
         document: any;
     }[]): Promise<never>;
 }
-/** Error thrown when an unsupported (write / auth-requiring) call is made on a
- *  read-only scoped client. */
+/** Error thrown when an unsupported (write) call is made on a scoped client.
+ *  Reads may be authenticated per instance; writes still are not supported. */
 export declare class ScopedClientReadOnlyError extends Error {
     constructor(operation: string);
 }
 /**
- * Create a read-only client scoped to a single Bounded app.
+ * Create a read-only client scoped to a single Bounded app, anonymous by default
+ * and authenticated when given `getAuthHeaders`.
  *
  * @example
  * ```ts
  * // Global client stays the venue's own authenticated app:
  * await init({ appId: VENUE_APP, network: 'bounded-production', authMethod: 'email' });
  *
- * // A second, read-only client for the steward runtime app:
+ * // A second, anonymous client for the steward runtime app's public collections:
  * const steward = createClient({ appId: STEWARD_APP, network: 'bounded-production' });
  * const state = await steward.get('runtime/current');
  * const stop = await steward.subscribe('runtime/current', (d) => render(d));
+ *
+ * // The same second app, read AS THE SIGNED-IN HUMAN: the venue session is
+ * // exchanged for a token pinned to the child app (see createAppTokenAuthHeaders).
+ * const mine = createClient({
+ *   appId: ROOT_APP,
+ *   network: 'bounded-production',
+ *   getAuthHeaders: createAppTokenAuthHeaders({
+ *     authApiUrl: HUMAN_AUTH_URL,
+ *     appId: ROOT_APP,
+ *     parentToken: () => getIdToken(),
+ *   }),
+ * });
+ * const stopChat = await mine.subscribe(`conversations/${id}/m`, (d) => render(d));
  * ```
  */
 export declare function createClient(config: CreateClientConfig): BoundedClient;

package/dist/client/subscription-v2.d.ts

@@ -5,6 +5,29 @@
  * It maintains the same external API as v1 but uses the new v2 protocol internally.
  */
 import { SubscriptionOptions } from '../types';
+/**
+ * Live subscriptions the SDK puts on ONE socket before opening another.
+ *
+ * The realtime worker refuses the 51st distinct subscribe on a connection with
+ * `{ code: 'subscription_limit', status: 429 }` - see
+ * `packages/cdk/cloudflare/realtime-worker/src/subscriptions.ts`
+ * (`attachment.subscriptions.length >= 50`). The cap is structural there: every
+ * subscription spec has to fit the 16KB Durable Object hibernation attachment,
+ * and each write fans out across the whole set of one socket.
+ *
+ * 45 leaves deliberate headroom under that 50: two concurrent subscribeV2 calls
+ * can both see room and overshoot by a frame or two, and another tab may already
+ * hold subscriptions on the same DO. A refusal that happens anyway is treated as
+ * backpressure, not a failure (see rehomeRefusedSubscription).
+ */
+export declare const SHARD_CAP = 45;
+/**
+ * Sockets one routing target (app, room, or wallet identity) may hold. Past this
+ * a subscribe fails loudly with `subscription_limit` instead of opening
+ * connections without end - 8 * 45 = 360 concurrent live subscriptions per
+ * target, far beyond any legitimate UI.
+ */
+export declare const MAX_SHARDS_PER_KEY = 8;
 /**
  * Subscribe to data at a path using WebSocket v2.
  * Returns an unsubscribe function.