@tangle-network/sandbox 0.0.0-develop.20260514223840.b2abd84

package/dist/index-Dpj1oB5i.d.ts

@@ -0,0 +1,220 @@
+//#region src/auth/types.d.ts
+/**
+ * Auth Types
+ *
+ * Self-contained type definitions for token issuance.
+ * No external dependencies (no zod, no internal packages).
+ */
+/**
+ * Token scope types for multi-tenant access control.
+ *
+ * - "session": Access to a single session (requires sid)
+ * - "project": Access to all sessions within a project (requires projectId)
+ * - "batch": Access to multiple projects (requires projectIds array)
+ * - "collaboration": Access to a single collaborative document
+ */
+type TokenScope = "session" | "project" | "batch" | "collaboration";
+/**
+ * Base token payload fields (common across all scopes).
+ */
+interface BaseTokenPayload {
+  /** Subject: User ID */
+  sub: string;
+  /** Product ID (used to look up signing secret) */
+  pid: string;
+  /** Sandbox runtime ID (optional, for direct routing) */
+  cid?: string;
+  /** Issued at (Unix timestamp, seconds) */
+  iat: number;
+  /** Expires at (Unix timestamp, seconds) */
+  exp: number;
+}
+interface ReadBaseTokenPayload extends BaseTokenPayload {
+  /** Token type for session/project/batch event subscriptions */
+  typ: "read";
+}
+/**
+ * Session-scoped token payload.
+ * Grants access to a single session's events.
+ */
+interface SessionScopedTokenPayload extends ReadBaseTokenPayload {
+  /** Session ID */
+  sid: string;
+  projectId?: undefined;
+  projectIds?: undefined;
+}
+/**
+ * Project-scoped token payload.
+ * Grants access to all sessions within a single project.
+ */
+interface ProjectScopedTokenPayload extends ReadBaseTokenPayload {
+  sid?: undefined;
+  /** Project ID */
+  projectId: string;
+  projectIds?: undefined;
+}
+/**
+ * Batch-scoped token payload.
+ * Grants access to multiple projects (organization-level access).
+ */
+interface BatchScopedTokenPayload extends ReadBaseTokenPayload {
+  sid?: undefined;
+  projectId?: undefined;
+  /** Project IDs */
+  projectIds: string[];
+}
+type CollaborationAccess = "read" | "write";
+/**
+ * Collaboration-scoped token payload.
+ * Grants access to a single collaborative document in one project.
+ */
+interface CollaborationTokenPayload extends BaseTokenPayload {
+  typ: "collaboration";
+  sid: string;
+  projectId: string;
+  documentId: string;
+  access: CollaborationAccess;
+}
+interface IssueCollaborationTokenOptions {
+  sessionId: string;
+  projectId: string;
+  documentId: string;
+  access: CollaborationAccess;
+  userId: string;
+  productId: string;
+  sandboxId?: string;
+}
+/**
+ * Union of all token payload types.
+ */
+type ReadTokenPayload = SessionScopedTokenPayload | ProjectScopedTokenPayload | BatchScopedTokenPayload;
+type AnyTokenPayload = ReadTokenPayload | CollaborationTokenPayload;
+//#endregion
+//#region src/auth/tokens.d.ts
+/**
+ * Issue a read token (JWT) for WebSocket authentication.
+ *
+ * @param signingSecret - The product's signing secret
+ * @param payload - Token payload (without iat/exp/typ, those are added)
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueReadToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a session-scoped token (JWT) for WebSocket authentication.
+ * Grants access to a single session's events.
+ */
+declare function issueSessionScopedToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a project-scoped token (JWT) for WebSocket authentication.
+ * Grants access to all sessions within a single project.
+ */
+declare function issueProjectScopedToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a batch-scoped token (JWT) for WebSocket authentication.
+ * Grants access to multiple projects (organization-level access).
+ */
+declare function issueBatchScopedToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a collaboration-scoped token (JWT) for collaborative document access.
+ * Grants read or write access to a single document in one project.
+ */
+declare function issueCollaborationToken(signingSecret: string, payload: IssueCollaborationTokenOptions, ttlMinutes: number): string;
+/**
+ * Decode a JWT **without verifying its signature**.
+ *
+ * The deliberately scary name is the API contract: an HMAC-signed token
+ * whose signature has not been verified is a self-asserted blob of JSON,
+ * not an authenticated claim. Treating its fields as authoritative
+ * (e.g. `if (unsafeDecodeToken(t).sub === userId) grantAccess()`) is a
+ * straightforward authorization bypass — an attacker can mint any
+ * payload they like.
+ *
+ * Use this only when the signature has already been validated upstream
+ * (e.g. by an API gateway that strips the token after verification),
+ * for client-side `exp` peeking to decide whether to refresh, or for
+ * routing/logging keyed off non-security-sensitive claims.
+ *
+ * For any access-control decision, use {@link verifyToken} instead.
+ *
+ * Returns `null` if the token is malformed.
+ */
+declare function unsafeDecodeToken(token: string): AnyTokenPayload | null;
+/**
+ * Verify a JWT's HMAC-SHA256 signature against `signingSecret` and
+ * check that it has not expired. Returns the decoded payload on
+ * success, or `null` on any failure (malformed token, bad signature,
+ * expired, or unexpected algorithm).
+ *
+ * Signature comparison is constant-time. Callers must use this — not
+ * {@link unsafeDecodeToken} — for any authorization decision.
+ *
+ * @param token - The JWT to verify
+ * @param signingSecret - The same secret used to issue the token
+ * @param options.clockSkewSeconds - Tolerance for `exp` checks; default `0`
+ */
+declare function verifyToken(token: string, signingSecret: string, options?: {
+  clockSkewSeconds?: number;
+}): AnyTokenPayload | null;
+/**
+ * Get time until token expires (in seconds).
+ * Returns negative if expired.
+ */
+declare function getTokenTTL(payload: AnyTokenPayload): number;
+/**
+ * Check if token is expiring soon (within buffer seconds).
+ */
+declare function isTokenExpiringSoon(payload: AnyTokenPayload, bufferSeconds?: number): boolean;
+//#endregion
+//#region src/auth/index.d.ts
+/**
+ * Token issuer for application backend services.
+ *
+ * Use this in your backend to issue read tokens for WebSocket connections.
+ */
+declare class ProductTokenIssuer {
+  private readonly productId;
+  private readonly signingSecret;
+  private readonly ttlMinutes;
+  constructor(config: {
+    productId: string;
+    signingSecret: string; /** TTL in minutes for each tier (default: { free: 15, pro: 240 }) */
+    ttlMinutes?: {
+      free?: number;
+      pro?: number;
+      enterprise?: number;
+    };
+  });
+  /**
+   * Issue a read token for a user session.
+   */
+  issue(params: {
+    userId: string;
+    sessionId: string;
+    tier?: "free" | "pro" | "enterprise";
+    sandboxId?: string;
+  }): {
+    token: string;
+    expiresAt: number;
+  };
+  /**
+   * Issue a collaboration token for a single document.
+   */
+  issueCollaboration(params: {
+    userId: string;
+    sessionId: string;
+    projectId: string;
+    documentId: string;
+    access: "read" | "write";
+    tier?: "free" | "pro" | "enterprise";
+    sandboxId?: string;
+  }): {
+    token: string;
+    expiresAt: number;
+  };
+  /**
+   * Get the TTL in minutes for a tier.
+   */
+  getTtlMinutes(tier?: "free" | "pro" | "enterprise"): number;
+}
+//#endregion
+export { ReadTokenPayload as _, issueCollaborationToken as a, issueSessionScopedToken as c, AnyTokenPayload as d, BatchScopedTokenPayload as f, ProjectScopedTokenPayload as g, IssueCollaborationTokenOptions as h, issueBatchScopedToken as i, unsafeDecodeToken as l, CollaborationTokenPayload as m, getTokenTTL as n, issueProjectScopedToken as o, CollaborationAccess as p, isTokenExpiringSoon as r, issueReadToken as s, ProductTokenIssuer as t, verifyToken as u, SessionScopedTokenPayload as v, TokenScope as y };