@astralbeam/sdk 0.2.0 → 0.3.0

package/README.md

@@ -40,16 +40,28 @@ import { createAstralBeamTokenRoute } from "@astralbeam/sdk/server"
 
 export const POST = createAstralBeamTokenRoute({
   apiKey: () => process.env.ASTRALBEAM_API_KEY, // key_<organization>_<key>_abo_<secret>
-  tenantUser: async (request) => {
-    const session = await getApplicationSession(request)
-    return session && { id: session.user.id, name: session.user.name }
-  },
+  authenticate: (request) => getApplicationSession(request),
+  user: (session) => ({
+    id: session.user.id,
+    name: session.user.name,
+    metadata: { email: session.user.email },
+  }),
+  tenant: (session) => ({
+    id: session.tenant.id,
+    name: session.tenant.name,
+    metadata: { plan: session.tenant.plan },
+  }),
 })
 ```
 
 - Add one endpoint, `/api/astralbeam/token` by default, that authenticates your own session first.
 - The factory owns the method check, the unconfigured 503, the unauthenticated 401, and `no-store`.
-- Derive `tenantUser` from trusted server-side state, never from anything the browser sent.
+- Authenticate once, then derive `user` and `tenant` separately from that same application session.
+- Derive `user` and `tenant` from trusted server-side state, never from anything the browser sent.
+- Provide stable tenant-local `user.id` and stable `tenant.id` values; names are optional, and set `user.admin` only from trusted state.
+- Put custom tenant and tenant-user fields in their respective `metadata` JSON objects; never include secrets.
+- SDK fields use camelCase; AstralBeam-owned JWT claims use snake_case, while `metadata` keys are preserved verbatim.
+- Tokens use the API key's organization slug as issuer and the platform audience `astralbeam`; AstralBeam does not require or interpret `sub`.
 - Tokens are signed, not encrypted: never put a secret in them.
 - Lifetimes are 60–600 seconds; the SDK renews in memory before expiry.
 

package/dist/server.d.ts

@@ -1,39 +1,57 @@
+import * as Schema from "effect/Schema";
+
 //#region src/server/index.d.ts
-declare const ASTRALBEAM_CHAT_TOKEN_AUDIENCE = "astralbeam-chat";
-declare const ASTRALBEAM_CHAT_TOKEN_ISSUER = "astralbeam-api-key";
-declare const ASTRALBEAM_CHAT_TOKEN_TYPE = "astralbeam-chat+jwt";
-declare const ASTRALBEAM_CHAT_TOKEN_VERSION = 2;
+declare const ASTRALBEAM_TOKEN_AUDIENCE = "astralbeam";
+declare const ASTRALBEAM_CHAT_TOKEN_TYPE = "astralbeam+jwt";
+declare const ASTRALBEAM_CHAT_TOKEN_VERSION = 4;
 declare const ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS = 300;
 declare const ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS = 600;
-interface TenantUser {
-  /** User of an Organization's Tenant who interacts with the embedded agent sidebar. */
-  readonly id: string;
-}
-interface CreateAstralBeamChatTokenOptions<TTenantUser extends TenantUser = TenantUser> {
+declare const TenantSchema: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly name: Schema.optional<Schema.String>;
+  readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+declare const TenantUserSchema: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly name: Schema.optional<Schema.String>;
+  readonly admin: Schema.optional<Schema.Boolean>;
+  readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+/** Tenant identity from the Organization's application, including JSON metadata. */
+type Tenant = typeof TenantSchema.Type;
+/** User of an Organization's Tenant who interacts with AstralBeam. */
+type TenantUser = typeof TenantUserSchema.Type;
+interface CreateAstralBeamChatTokenOptions<TTenantUser extends TenantUser = TenantUser, TTenant extends Tenant = Tenant> {
   readonly apiKey: string;
-  readonly tenantUser: TTenantUser;
+  readonly user: TTenantUser;
+  readonly tenant: TTenant;
   readonly expiresInSeconds?: number | undefined;
 }
-interface CreateAstralBeamTokenRouteOptions<TTenantUser extends TenantUser = TenantUser> {
+interface CreateAstralBeamTokenRouteOptions<TSession extends object = object, TTenantUser extends TenantUser = TenantUser, TTenant extends Tenant = Tenant> {
   /** The full API key, or a thunk read per request; missing or empty answers 503. */
   readonly apiKey: string | undefined | (() => string | undefined);
   /**
-   * Authenticates the request against the application's own session and returns the tenant
-   * user minted into the token. Returning nothing, or throwing, answers 401.
+   * Authenticates the request against the application's own session. Returning nothing, or
+   * throwing, answers 401.
    */
-  readonly tenantUser: (request: Request) => TTenantUser | null | undefined | Promise<TTenantUser | null | undefined>;
+  readonly authenticate: (request: Request) => TSession | null | undefined | Promise<TSession | null | undefined>;
+  /** Maps the authenticated session to the tenant user minted into the token. */
+  readonly user: (session: TSession) => TTenantUser;
+  /** Maps the same authenticated session to the tenant minted into the token. */
+  readonly tenant: (session: TSession) => TTenant;
   readonly expiresInSeconds?: number | undefined;
 }
 /**
  * Builds the fetch-standard `POST` handler for an application's token endpoint, owning the
  * method check, the unconfigured-key 503, the unauthenticated 401, and the `no-store` header.
  */
-declare function createAstralBeamTokenRoute<TTenantUser extends TenantUser = TenantUser>(options: CreateAstralBeamTokenRouteOptions<TTenantUser>): (request: Request) => Promise<Response>;
+declare function createAstralBeamTokenRoute<TSession extends object, TTenantUser extends TenantUser = TenantUser, TTenant extends Tenant = Tenant>(options: CreateAstralBeamTokenRouteOptions<TSession, TTenantUser, TTenant>): (request: Request) => Promise<Response>;
 /** Creates the short-lived bearer token returned by an application's server auth endpoint. */
-declare function createAstralBeamChatToken<TTenantUser extends TenantUser = TenantUser>({
+declare function createAstralBeamChatToken<TTenantUser extends TenantUser = TenantUser, TTenant extends Tenant = Tenant>({
   apiKey,
-  tenantUser,
+  user,
+  tenant,
   expiresInSeconds
-}: CreateAstralBeamChatTokenOptions<TTenantUser>): Promise<string>;
+}: CreateAstralBeamChatTokenOptions<TTenantUser, TTenant>): Promise<string>;
 //#endregion
-export { ASTRALBEAM_CHAT_TOKEN_AUDIENCE, ASTRALBEAM_CHAT_TOKEN_ISSUER, ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_TYPE, ASTRALBEAM_CHAT_TOKEN_VERSION, CreateAstralBeamChatTokenOptions, CreateAstralBeamTokenRouteOptions, TenantUser, createAstralBeamChatToken, createAstralBeamTokenRoute };
+export { ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_TYPE, ASTRALBEAM_CHAT_TOKEN_VERSION, ASTRALBEAM_TOKEN_AUDIENCE, CreateAstralBeamChatTokenOptions, CreateAstralBeamTokenRouteOptions, Tenant, TenantSchema, TenantUser, TenantUserSchema, createAstralBeamChatToken, createAstralBeamTokenRoute };

package/dist/server.js

@@ -638,54 +638,64 @@ var SignJWT = class {
 };
 //#endregion
 //#region src/server/index.ts
-const ASTRALBEAM_CHAT_TOKEN_AUDIENCE = "astralbeam-chat";
-const ASTRALBEAM_CHAT_TOKEN_ISSUER = "astralbeam-api-key";
-const ASTRALBEAM_CHAT_TOKEN_TYPE = "astralbeam-chat+jwt";
-const ASTRALBEAM_CHAT_TOKEN_VERSION = 2;
+const ASTRALBEAM_TOKEN_AUDIENCE = "astralbeam";
+const ASTRALBEAM_CHAT_TOKEN_TYPE = "astralbeam+jwt";
+const ASTRALBEAM_CHAT_TOKEN_VERSION = 4;
 const ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS = 300;
 const ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS = 600;
-const API_KEY_ID_PATTERN = /^key_[0-9a-z]{1,63}_([0-9a-z]{1,63})$/;
-const API_KEY_SECRET_PATTERN = /^abo_[A-Za-z]{64}$/;
 const CHAT_TOKEN_MAX_BYTES = 16384;
-const TENANT_USER_MAX_BYTES = 8192;
-const TENANT_USER_MAX_DEPTH = 10;
+const IDENTITY_MAX_BYTES = 8192;
 const textEncoder = new TextEncoder();
-const TenantUserJsonSchema = Schema.Json.annotate({ message: "tenantUser must contain only JSON values" });
-const TenantUserSchema = Schema.StructWithRest(Schema.Struct({ id: Schema.String.pipe(Schema.check(Schema.makeFilter((value) => value.length >= 1 && value.length <= 255, { message: "tenantUser.id must be a 1-255 character string" }))) }), [Schema.Record(Schema.String, TenantUserJsonSchema)]).pipe(Schema.check(Schema.makeFilter((value) => !exceedsJsonDepth(value, TENANT_USER_MAX_DEPTH), { message: `tenantUser must not exceed ${TENANT_USER_MAX_DEPTH} levels` })), Schema.check(Schema.makeFilter((value) => textEncoder.encode(JSON.stringify(value)).byteLength <= TENANT_USER_MAX_BYTES, { message: `tenantUser must not exceed ${TENANT_USER_MAX_BYTES} bytes` })));
-const decodeTenantUser = Schema.decodeUnknownSync(TenantUserSchema, {
+const SlugSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^[0-9a-z-]{1,63}$/)));
+const ApiKeySecretSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^abo_[A-Za-z]{64}$/)));
+const ApiKeySchema = Schema.TemplateLiteral([
+	"key_",
+	SlugSchema,
+	"_",
+	SlugSchema,
+	"_",
+	ApiKeySecretSchema
+]);
+const isApiKey = Schema.is(ApiKeySchema);
+const MetadataSchema = Schema.JsonObject.annotate({ message: "metadata must be a JSON object" });
+const TenantExternalIdSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => value.length >= 1 && value.length <= 255, { message: "tenant.id must be a 1-255 character string" })));
+const TenantUserExternalIdSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => value.length >= 1 && value.length <= 255, { message: "user.id must be a 1-255 character string" })));
+const TenantSchema = Schema.Struct({
+	id: TenantExternalIdSchema,
+	name: Schema.optional(Schema.String),
+	metadata: Schema.optional(MetadataSchema)
+});
+const TenantUserSchema = Schema.Struct({
+	id: TenantUserExternalIdSchema,
+	name: Schema.optional(Schema.String),
+	admin: Schema.optional(Schema.Boolean),
+	metadata: Schema.optional(MetadataSchema)
+});
+const IdentitySchema = Schema.Struct({
+	user: TenantUserSchema,
+	tenant: TenantSchema
+}).pipe(Schema.check(Schema.makeFilter((value) => textEncoder.encode(JSON.stringify(value)).byteLength <= IDENTITY_MAX_BYTES, { message: `user and tenant must not exceed ${IDENTITY_MAX_BYTES} bytes` })));
+const decodeIdentity = Schema.decodeUnknownSync(IdentitySchema, {
 	errors: "all",
 	onExcessProperty: "error",
 	reportInput: false
 });
 function parseApiKey(apiKey) {
+	if (!isApiKey(apiKey)) throw new Error("apiKey must match key_<organization>_<key>_abo_<secret>");
 	const separator = apiKey.lastIndexOf("_abo_");
-	const id = apiKey.slice(0, separator);
-	const secret = apiKey.slice(separator + 1);
-	if (!API_KEY_ID_PATTERN.test(id) || !API_KEY_SECRET_PATTERN.test(secret)) throw new Error("apiKey must match key_<organization>_<key>_abo_<secret>");
+	const keyId = apiKey.slice(0, separator);
+	const keySecret = apiKey.slice(separator + 1);
 	return {
-		id,
-		secret
+		keyId,
+		organizationSlug: keyId.slice(4, keyId.indexOf("_", 4)),
+		keySecret
 	};
 }
-function exceedsJsonDepth(value, maximumDepth) {
-	const stack = [{
-		value,
-		depth: 1
-	}];
-	while (stack.length > 0) {
-		const current = stack.pop();
-		if (current.depth > maximumDepth) return true;
-		if (typeof current.value !== "object" || current.value === null) continue;
-		const children = Array.isArray(current.value) ? current.value : Object.values(current.value);
-		for (const child of children) stack.push({
-			value: child,
-			depth: current.depth + 1
-		});
-	}
-	return false;
-}
-function validatedTenantUser(value) {
-	return JSON.parse(JSON.stringify(decodeTenantUser(value)));
+function validatedIdentity(user, tenant) {
+	return JSON.parse(JSON.stringify(decodeIdentity({
+		user,
+		tenant
+	})));
 }
 async function signingKey(secret) {
 	const digest = await crypto.subtle.digest("SHA-256", textEncoder.encode(secret));
@@ -706,17 +716,18 @@ function createAstralBeamTokenRoute(options) {
 		if (request.method !== "POST") return tokenRouteResponse({ error: "Use POST" }, 405);
 		const apiKey = typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
 		if (!apiKey) return tokenRouteResponse({ error: "The AstralBeam API key is not configured" }, 503);
-		let tenantUser;
+		let session;
 		try {
-			tenantUser = await options.tenantUser(request);
+			session = await options.authenticate(request);
 		} catch {
-			tenantUser = void 0;
+			session = void 0;
 		}
-		if (!tenantUser) return tokenRouteResponse({ error: "The session could not be verified" }, 401);
+		if (!session) return tokenRouteResponse({ error: "The session could not be verified" }, 401);
 		try {
 			return tokenRouteResponse({ token: await createAstralBeamChatToken({
 				apiKey,
-				tenantUser,
+				user: options.user(session),
+				tenant: options.tenant(session),
 				...options.expiresInSeconds === void 0 ? {} : { expiresInSeconds: options.expiresInSeconds }
 			}) }, 200);
 		} catch {
@@ -725,21 +736,22 @@ function createAstralBeamTokenRoute(options) {
 	};
 }
 /** Creates the short-lived bearer token returned by an application's server auth endpoint. */
-async function createAstralBeamChatToken({ apiKey, tenantUser, expiresInSeconds = 300 }) {
+async function createAstralBeamChatToken({ apiKey, user, tenant, expiresInSeconds = 300 }) {
 	if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 60 || expiresInSeconds > 600) throw new Error("AstralBeam chat tokens must live for 60-600 seconds");
-	const { id: apiKeyId, secret } = parseApiKey(apiKey);
-	const identity = validatedTenantUser(tenantUser);
+	const { keyId, organizationSlug, keySecret } = parseApiKey(apiKey);
+	const identity = validatedIdentity(user, tenant);
 	const now = Math.floor(Date.now() / 1e3);
 	const token = await new SignJWT({
-		ver: 2,
-		tenantUser: identity
+		ver: 4,
+		user: identity.user,
+		tenant: identity.tenant
 	}).setProtectedHeader({
 		alg: "HS256",
 		typ: ASTRALBEAM_CHAT_TOKEN_TYPE,
-		kid: apiKeyId
-	}).setIssuer(ASTRALBEAM_CHAT_TOKEN_ISSUER).setAudience(ASTRALBEAM_CHAT_TOKEN_AUDIENCE).setSubject(tenantUser.id).setIssuedAt(now).setExpirationTime(now + expiresInSeconds).sign(await signingKey(secret));
+		kid: keyId
+	}).setIssuer(organizationSlug).setAudience(ASTRALBEAM_TOKEN_AUDIENCE).setIssuedAt(now).setExpirationTime(now + expiresInSeconds).sign(await signingKey(keySecret));
 	if (textEncoder.encode(token).byteLength > CHAT_TOKEN_MAX_BYTES) throw new Error(`AstralBeam chat tokens must not exceed ${CHAT_TOKEN_MAX_BYTES} bytes`);
 	return token;
 }
 //#endregion
-export { ASTRALBEAM_CHAT_TOKEN_AUDIENCE, ASTRALBEAM_CHAT_TOKEN_ISSUER, ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_TYPE, ASTRALBEAM_CHAT_TOKEN_VERSION, createAstralBeamChatToken, createAstralBeamTokenRoute };
+export { ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_TYPE, ASTRALBEAM_CHAT_TOKEN_VERSION, ASTRALBEAM_TOKEN_AUDIENCE, TenantSchema, TenantUserSchema, createAstralBeamChatToken, createAstralBeamTokenRoute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astralbeam/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Frontend SDK for AstralBeam: drop-in agent UI, chat streaming, and server helpers",
   "license": "MIT",
   "type": "module",