@plitzi/sdk-server 0.32.25 → 0.33.0

package/dist/core/auth/authorize.js

@@ -0,0 +1,92 @@
+//#region src/core/auth/authorize.ts
+var matches = (path, matchers) => matchers.some((matcher) => {
+	if (matcher instanceof RegExp) return matcher.test(path);
+	return typeof matcher === "function" ? matcher(path) : matcher === path;
+});
+var requirementFor = (policy, path) => policy.rules.find((rule) => matches(path, rule.match))?.requirement ?? policy.fallback;
+/**
+* Decides whether a request may proceed, and with what identity — the same decision on every transport, which is
+* the point of it living here rather than inside one framework's middleware. Callers bind it to their own: Express
+* puts the result on `req` and answers 401 itself, this server's pipeline does the same with its own response.
+*/
+var createAuthorizer = (identity, policy) => async (carrier, path) => {
+	const requirement = requirementFor(policy, path);
+	if (requirement === "public") return { ok: true };
+	const [actorResult, grantResult] = await Promise.all([identity.resolveActor(carrier), identity.resolveGrant(carrier)]);
+	const actor = actorResult.ok && actorResult.actor.verified ? actorResult.actor : void 0;
+	const grant = grantResult.ok ? grantResult.grant : void 0;
+	if ((requirement === "grant" || requirement === "grant+actor") && !grant) return {
+		ok: false,
+		status: 401,
+		reason: grantResult.ok ? "missing" : grantResult.reason
+	};
+	if (requirement === "actor" || requirement === "grant+actor") {
+		if (!actorResult.ok) return {
+			ok: false,
+			status: 401,
+			reason: actorResult.reason
+		};
+		if (!actor) return {
+			ok: false,
+			status: 401,
+			reason: "inactive"
+		};
+	}
+	return {
+		ok: true,
+		actor,
+		grant
+	};
+};
+/**
+* A global capability, checked off the actor the guard already resolved — no query. This is the whole of RBAC that
+* applies outside a space: platform-wide routes rather than "may you touch this space", which is `identity.can()` and
+* needs the membership half too.
+*
+* An answer rather than a middleware, so it reads the same from any host. The distinction it exists to make is 401
+* against 403: "nobody is here" and "you are here and this is not yours" are different facts, and collapsing them
+* tells a signed-in caller to sign in again.
+*/
+var checkPermission = (actor, permission) => {
+	if (!actor?.id) return {
+		ok: false,
+		status: 401,
+		error: "Not authenticated"
+	};
+	if (!actor.permissions.includes(permission)) return {
+		ok: false,
+		status: 403,
+		error: "Insufficient permissions"
+	};
+	return { ok: true };
+};
+/**
+* The space half: may this actor act on this space at all, and is being its owner required?
+*
+* The answer that matters is the middle one. A non-member gets **404, not 403** — telling a stranger "you may not
+* touch this space" confirms the space exists, and whether a given slug belongs to somebody is not a fact an
+* outsider gets to establish by asking. Owners and members are told apart afterwards, because by then the caller has
+* already proved they belong there and 403 gives away nothing.
+*
+* Resolving the membership is the deployment's — its tables, and whether a route names a space by id or by slug.
+*/
+var checkSpaceAccess = (actor, membership, { owner = false } = {}) => {
+	if (!actor?.id) return {
+		ok: false,
+		status: 401,
+		error: "Not authenticated"
+	};
+	if (!membership) return {
+		ok: false,
+		status: 404,
+		error: "Space not found"
+	};
+	if (owner && !membership.isOwner) return {
+		ok: false,
+		status: 403,
+		error: "Insufficient permissions"
+	};
+	return { ok: true };
+};
+//#endregion
+export { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor };

package/dist/core/auth/createAuth.d.ts

@@ -0,0 +1,165 @@
+import { AccountAdapters, AuthApiConfig } from './api';
+import { AuthPolicy, Requirement } from './authorize';
+import { CredentialCarrier } from './credentials';
+import { IdentityAdapters, IdentityConfig } from './identity';
+import { TokenConfig } from './tokens';
+import { SSRAuthCookie, SSRSession, SSRUser } from '@plitzi/sdk-shared';
+/**
+ * Everything a deployment says about its own auth, in one object.
+ *
+ * The pieces underneath stay exported and composable — a host that wants to build the identity resolver alone, or
+ * swap one stage, still can. This exists because assembling them is not where anybody's judgement should go: there
+ * is one correct order, and the two facts that appear in more than one place have to agree.
+ *
+ * The cookie name is the one that mattered. It was stated twice — once for the readers that pull a credential off a
+ * request, once for the writers that put it there — and a deployment that changed one and not the other wrote its
+ * session under a name nothing read it back from. A session that silently does not exist, from a typo. Here it is
+ * said once and both sides derive from it.
+ */
+export interface AuthConfig {
+    /** The signing secret and the issuer that separate this deployment's credentials from every other's. */
+    tokens: TokenConfig;
+    /**
+     * What this deployment calls its session cookies, and where they are scoped. Defaults derive from the request
+     * host, which is right for a single-host deployment and wrong the moment an app and an API share a domain.
+     */
+    cookie?: SSRAuthCookie;
+    /**
+     * The stores auth reads and writes. Identity is what the guard needs on every request; the account half is what
+     * the `/auth` flows need, and **what is absent decides what this deployment offers** — no `createAccount`, no
+     * signup, and the route answers 404 rather than failing at runtime.
+     */
+    adapters: IdentityAdapters & AccountAdapters;
+    /** This deployment's own hosts and origins, and how it logs a refusal. */
+    identity?: IdentityConfig;
+    /** Password hashing, token generation, and which flows to offer at all. */
+    api?: AuthApiConfig;
+    /** Where the `/auth` flows are mounted, so the policy matches the routes. Default `/auth`. */
+    basePath?: string;
+    /** What a path with no rule of its own requires. Default `actor` — anything unlisted needs a session. */
+    fallback?: Requirement;
+    /** Extra rules, applied BEFORE the derived `/auth` ones so a deployment can always widen its own surface. */
+    rules?: AuthPolicy['rules'];
+}
+/**
+ * The whole auth cycle, wired.
+ *
+ * ```ts
+ * const auth = createAuth({
+ *   tokens: { secret, issuer: 'https://acme.test', audience: ['https://api.acme.test'] },
+ *   cookie: { name: 'acme_session' },
+ *   adapters: myStore
+ * });
+ *
+ * // guard every request
+ * const result = await auth.authorize(req, req.url);
+ * // serve the flows
+ * for (const { method, path, handler } of auth.routes) { … }
+ * ```
+ */
+export declare const createAuth: (config: AuthConfig) => {
+    tokens: {
+        lifetimes: {
+            access: 86400;
+            refresh: number;
+            agent: number;
+            widget: number;
+        };
+        generateUserToken: (userId: number | string) => string;
+        generateRefreshToken: (userId: number | string) => string;
+        generateWidgetToken: () => string;
+        generateSpaceToken: (spaceId: number | string, origins: string[], scope?: import('./tokens').SpaceScope, { expiresAt }?: import('./tokens').SpaceTokenOptions) => string;
+        verifyUserToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').UserTokenPayload>;
+        verifyRefreshToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').RefreshTokenPayload>;
+        verifyWidgetToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').WidgetTokenPayload>;
+        verifySpaceToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').SpaceTokenPayload & {
+            spaceId: number;
+            spaceScope: import('./tokens').SpaceScope;
+        }>;
+        needsRotation: (token: string) => boolean;
+        expiresInSeconds: (token: string) => number | undefined;
+    };
+    identity: {
+        resolveActor: (carrier: CredentialCarrier) => Promise<import('./identity').ActorResult>;
+        resolveActorFromToken: (token: string) => Promise<import('./identity').ActorResult>;
+        resolveGrant: (carrier: CredentialCarrier, options?: import('./identity').GrantOptions) => Promise<import('./identity').GrantResult>;
+        resolveGrantFromToken: (token: string, origin: string, { skipOrigin, host }?: import('./identity').GrantOptions) => Promise<import('./identity').GrantResult>;
+        can: (actor: import('./identity').Actor, spaceId: number, permission: string) => Promise<boolean>;
+        grantCan: (grant: import('./identity').Grant, permission: string) => Promise<boolean>;
+    };
+    api: {
+        capabilities: {
+            passwordLogin: boolean;
+            refresh: boolean;
+            signup: boolean;
+            passwordReset: boolean;
+            emailVerification: boolean;
+            exchange: boolean;
+        };
+        describe: () => import('./api').AuthOutcome;
+        session: (actor?: import('./identity').Actor) => import('./api').AuthOutcome;
+        login: (credentials: Record<string, unknown>) => Promise<import('./api').AuthOutcome>;
+        refresh: (refreshToken?: string) => Promise<import('./api').AuthOutcome>;
+        logout: (credentials: {
+            accessToken?: string;
+            refreshToken?: string;
+        }) => Promise<import('./api').AuthOutcome>;
+        revokeSessions: (userId?: number) => Promise<import('./api').AuthOutcome>;
+        exchange: (provider: string, token: string, carrier: CredentialCarrier) => Promise<import('./api').AuthOutcome>;
+        signup: (fields: Record<string, unknown>) => Promise<import('./api').AuthOutcome>;
+        forgotPassword: (email: string) => Promise<import('./api').AuthOutcome>;
+        resetPassword: (token: string, password: string) => Promise<import('./api').AuthOutcome>;
+        validateAccount: (token: string) => Promise<import('./api').AuthOutcome>;
+        resendVerification: (email: string) => Promise<import('./api').AuthOutcome>;
+        issueSession: (userId: number) => Promise<SSRSession>;
+        resolveActor: (carrier: CredentialCarrier) => Promise<import('./identity').ActorResult>;
+    };
+    cookies: {
+        write: (req: {
+            hostname: string;
+        }, res: import('./session').CookieSink, session: SSRSession) => void;
+        clear: (req: {
+            hostname: string;
+        }, res: import('./session').CookieSink) => void;
+        writeFlow: (req: {
+            hostname: string;
+        }, res: import('./session').CookieSink, value: string, ttlSeconds: number) => void;
+        clearFlow: (req: {
+            hostname: string;
+        }, res: import('./session').CookieSink) => void;
+        readFlow: (req: import('./session').CookieCarrier) => string | undefined;
+        resolveSessionToken: (req: import('./session').CookieCarrier) => string | undefined;
+        resolveRefreshToken: (req: import('./session').CookieCarrier, body?: unknown) => string | undefined;
+    };
+    policy: AuthPolicy;
+    /** Where these flows were mounted, so whatever serves them reads it here rather than defaulting to `/auth`
+     *  on its own — a host that guessed would serve the routes somewhere the policy above does not guard. */
+    basePath: string;
+    /** The naming this was built with, so a page server takes it from here instead of being told a second time. */
+    cookieConfig: SSRAuthCookie | undefined;
+    /** The `/auth` flows as descriptors, ready for whatever serves HTTP here. */
+    routes: import('./routes').AuthRoute[];
+    /** May this request proceed, and as whom. */
+    authorize: (carrier: CredentialCarrier, path: string) => Promise<import('./authorize').AuthorizeResult>;
+    /** Does what a flow's answer says about the session cookies. */
+    applySession: (req: {
+        hostname: string;
+    }, res: import('./session').CookieSink, outcome: import('./api').AuthOutcome, cookies: import('./session').SessionCookies) => void;
+    /** Both halves of a space permission: a global capability, and membership of that space. */
+    can: (actor: import('./identity').Actor, spaceId: number, permission: string) => Promise<boolean>;
+    /**
+     * The three adapters a page server asks for, already answered. Spread these into `createServer`'s `adapters`
+     * and a rendered page knows who is looking at it, `POST /auth/login` signs them in, `POST /auth/logout` signs
+     * them out, and the cookies are written and cleared by the same code that reads them back.
+     *
+     * They exist because the page server speaks in sessions and users while the flows above answer in outcomes,
+     * and translating between the two is a step with exactly one right answer — which makes it the server's, not
+     * something for every deployment to rediscover.
+     */
+    ssrAdapters: {
+        authenticate: (credentials: Record<string, string>) => Promise<SSRSession | undefined>;
+        getUser: (req: CredentialCarrier) => Promise<SSRUser | undefined>;
+        endSession: (req: CredentialCarrier) => Promise<void>;
+    };
+};
+export type Auth = ReturnType<typeof createAuth>;

package/dist/core/auth/createAuth.js

@@ -0,0 +1,105 @@
+import { createSessionCookies, sessionCookieParams } from "./session.js";
+import { createTokens } from "./tokens.js";
+import { createCarriers, presentedOrigin } from "./credentials.js";
+import { createIdentity } from "./identity.js";
+import { createAuthorizer } from "./authorize.js";
+import { createAuthApi } from "./api.js";
+import { applySessionOutcome, authPolicyRules, authRoutes } from "./routes.js";
+//#region src/core/auth/createAuth.ts
+/**
+* The whole auth cycle, wired.
+*
+* ```ts
+* const auth = createAuth({
+*   tokens: { secret, issuer: 'https://acme.test', audience: ['https://api.acme.test'] },
+*   cookie: { name: 'acme_session' },
+*   adapters: myStore
+* });
+*
+* // guard every request
+* const result = await auth.authorize(req, req.url);
+* // serve the flows
+* for (const { method, path, handler } of auth.routes) { … }
+* ```
+*/
+var createAuth = (config) => {
+	const tokens = createTokens(config.tokens);
+	const cookieName = (hostname) => sessionCookieParams(hostname, config.cookie).name;
+	const cookies = createSessionCookies(config.cookie);
+	const identity = createIdentity({
+		tokens,
+		carriers: createCarriers(cookieName),
+		presentedOrigin,
+		adapters: config.adapters,
+		config: config.identity
+	});
+	const api = createAuthApi({
+		tokens,
+		identity,
+		adapters: config.adapters,
+		config: config.api
+	});
+	const basePath = config.basePath ?? "/auth";
+	const policy = {
+		rules: [...config.rules ?? [], ...authPolicyRules(basePath)],
+		fallback: config.fallback ?? "actor"
+	};
+	return {
+		tokens,
+		identity,
+		api,
+		cookies,
+		policy,
+		/** Where these flows were mounted, so whatever serves them reads it here rather than defaulting to `/auth`
+		*  on its own — a host that guessed would serve the routes somewhere the policy above does not guard. */
+		basePath,
+		/** The naming this was built with, so a page server takes it from here instead of being told a second time. */
+		cookieConfig: config.cookie,
+		/** The `/auth` flows as descriptors, ready for whatever serves HTTP here. */
+		routes: authRoutes({
+			api,
+			cookies
+		}),
+		/** May this request proceed, and as whom. */
+		authorize: createAuthorizer(identity, policy),
+		/** Does what a flow's answer says about the session cookies. */
+		applySession: applySessionOutcome,
+		/** Both halves of a space permission: a global capability, and membership of that space. */
+		can: identity.can,
+		/**
+		* The three adapters a page server asks for, already answered. Spread these into `createServer`'s `adapters`
+		* and a rendered page knows who is looking at it, `POST /auth/login` signs them in, `POST /auth/logout` signs
+		* them out, and the cookies are written and cleared by the same code that reads them back.
+		*
+		* They exist because the page server speaks in sessions and users while the flows above answer in outcomes,
+		* and translating between the two is a step with exactly one right answer — which makes it the server's, not
+		* something for every deployment to rediscover.
+		*/
+		ssrAdapters: {
+			authenticate: async (credentials) => {
+				const outcome = await api.login(credentials);
+				return outcome.ok ? outcome.session : void 0;
+			},
+			getUser: async (req) => {
+				const resolved = await identity.resolveActor(req);
+				if (!resolved.ok) return;
+				const { id, username, email, verified, permissions, roles, token, expiresAt } = resolved.actor;
+				return {
+					id,
+					username,
+					email,
+					verified,
+					permissions,
+					roles,
+					token,
+					expiresAt
+				};
+			},
+			endSession: async (req) => {
+				await api.logout({ accessToken: cookies.resolveSessionToken(req) });
+			}
+		}
+	};
+};
+//#endregion
+export { createAuth };

package/dist/core/auth/credentials.d.ts

@@ -0,0 +1,29 @@
+import { IncomingHttpHeaders } from 'node:http';
+/**
+ * The shape both an Express `Request` and this server's own `SSRRequest` satisfy. Everything that reads a credential
+ * off a request goes through it, so header/cookie precedence is stated once instead of once per transport.
+ */
+export interface CredentialCarrier {
+    headers: IncomingHttpHeaders;
+    hostname: string;
+    query?: Record<string, unknown>;
+    /** Populated by cookie-parser on Express; absent elsewhere, where the header is parsed. */
+    cookies?: Record<string, string>;
+}
+/**
+ * Where a credential of each kind is allowed to ride.
+ *
+ * `Authorization: Bearer` carries a session token on one role and a space token on another, so it is a candidate for
+ * both and the typed verifier decides which it actually is — that is what `scope` is for. Trying the wrong kind
+ * costs nothing: it fails on its scope claim before any database is touched.
+ */
+export declare const createCarriers: (sessionCookieName: (hostname: string) => string) => {
+    userTokenCandidates: (carrier: CredentialCarrier) => string[];
+    spaceTokenCandidates: (carrier: CredentialCarrier) => string[];
+};
+/**
+ * The origin the caller claims to be presenting from — the `Origin` header, falling back to the host it addressed.
+ * Distinct from this server's own origin (see `requestOrigin` in the request parser): this one is the claim a
+ * credential's domain binding is checked against.
+ */
+export declare const presentedOrigin: (carrier: CredentialCarrier) => string;

package/dist/core/auth/credentials.js

@@ -0,0 +1,48 @@
+//#region src/core/auth/credentials.ts
+var parseCookieHeader = (cookieHeader) => {
+	const cookies = {};
+	for (const part of cookieHeader.split(";")) {
+		const eqIndex = part.indexOf("=");
+		if (eqIndex === -1) continue;
+		cookies[part.slice(0, eqIndex).trim()] = decodeURIComponent(part.slice(eqIndex + 1).trim());
+	}
+	return cookies;
+};
+var readCookies = (carrier) => {
+	if (carrier.cookies) return carrier.cookies;
+	const cookieHeader = carrier.headers.cookie;
+	return cookieHeader ? parseCookieHeader(cookieHeader) : {};
+};
+var headerValue = (value) => (Array.isArray(value) ? value[0] : value)?.trim() ?? "";
+var bearer = (carrier) => headerValue(carrier.headers.authorization).replace(/^Bearer\s+/i, "");
+var unique = (candidates) => [...new Set(candidates.filter(Boolean))];
+/**
+* Where a credential of each kind is allowed to ride.
+*
+* `Authorization: Bearer` carries a session token on one role and a space token on another, so it is a candidate for
+* both and the typed verifier decides which it actually is — that is what `scope` is for. Trying the wrong kind
+* costs nothing: it fails on its scope claim before any database is touched.
+*/
+var createCarriers = (sessionCookieName) => ({
+	userTokenCandidates: (carrier) => unique([
+		headerValue(carrier.headers["plitzi-access-token"]),
+		bearer(carrier),
+		readCookies(carrier)[sessionCookieName(carrier.hostname)] ?? ""
+	]),
+	spaceTokenCandidates: (carrier) => {
+		const queryToken = carrier.query?.["access-token"];
+		return unique([
+			headerValue(carrier.headers["x-access-token"]),
+			bearer(carrier),
+			typeof queryToken === "string" ? queryToken : ""
+		]);
+	}
+});
+/**
+* The origin the caller claims to be presenting from — the `Origin` header, falling back to the host it addressed.
+* Distinct from this server's own origin (see `requestOrigin` in the request parser): this one is the claim a
+* credential's domain binding is checked against.
+*/
+var presentedOrigin = (carrier) => headerValue(carrier.headers.origin) || carrier.hostname;
+//#endregion
+export { createCarriers, presentedOrigin };

package/dist/core/auth/domains.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Declared domains are stored and signed as full origins (`https://site.example.com`) while a request host is bare
+ * (`site.example.com`), so both sides are reduced to a hostname before being compared. A non-web value still reduces
+ * to something — `plitzi-desktop` to itself, `chrome-extension://…` to its authority — but neither is a host a
+ * request ever reports, so it never matches.
+ */
+export declare const hostnameOf: (value: string) => string;
+/** The wildcard a space sets when its embed target is genuinely unknown. Named so an API can warn about it. */
+export declare const ANY_DOMAIN = "*";
+/**
+ * May a token declaring `origins` be presented on `host`?
+ *
+ * `platformHosts` are this deployment's own — its builder, its renderer, its MCP endpoint — which serve first-party
+ * traffic for every space and are therefore valid destinations for any token, whatever domains it declares. They are
+ * passed in rather than read from configuration here because only the deployment knows what it runs.
+ */
+export declare const domainAllowed: (host: string, origins: string[], platformHosts?: string[]) => boolean;
+/**
+ * User input arrives as whatever someone typed — `example.com`, `https://example.com/`, `HTTPS://Example.com/x`. It
+ * is stored as a canonical origin so the signed claim, the stored column and the comparison all agree.
+ */
+export declare const normalizeDomain: (value: string) => string | undefined;
+/**
+ * Who may put this space in an iframe, as CSP `frame-ancestors` sources.
+ *
+ * The deployment's own hosts are the floor — a builder previews every space in one — and a space widens it with the
+ * domains its owner declared. `*` opts out entirely. Without this a published space is framable from any site on the
+ * web, which is how one customer wraps another's space inside their own page and passes it off as theirs.
+ *
+ * Unlike the token's domain binding, this one is enforced by the browser, which is why it is worth stating even
+ * though a determined caller can ignore the header: it stops the attack that needs a real visitor's browser.
+ */
+export declare const frameAncestors: (declared: string[], platformHosts?: string[]) => string[];
+/**
+ * Which origins a request bearing this grant may be answered for.
+ *
+ * A space is reachable from the origins its own token declares, plus this deployment's own apps; `*` means anywhere,
+ * and a grant that declares nothing at all falls back to the deployment's own unless it allows anonymous origins.
+ * Returning `true` means "reflect whatever asked", which is what a CORS layer wants for the wildcard case.
+ */
+export declare const corsOrigins: (declared: string[] | undefined, platformOrigins?: string[], allowWithoutOrigin?: boolean) => true | string[];

package/dist/core/auth/domains.js

@@ -0,0 +1,78 @@
+//#region src/core/auth/domains.ts
+/**
+* Declared domains are stored and signed as full origins (`https://site.example.com`) while a request host is bare
+* (`site.example.com`), so both sides are reduced to a hostname before being compared. A non-web value still reduces
+* to something — `plitzi-desktop` to itself, `chrome-extension://…` to its authority — but neither is a host a
+* request ever reports, so it never matches.
+*/
+var hostnameOf = (value) => {
+	const trimmed = value.trim().toLowerCase();
+	if (!trimmed) return "";
+	try {
+		return new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`).hostname;
+	} catch {
+		return "";
+	}
+};
+/** The wildcard a space sets when its embed target is genuinely unknown. Named so an API can warn about it. */
+var ANY_DOMAIN = "*";
+/**
+* May a token declaring `origins` be presented on `host`?
+*
+* `platformHosts` are this deployment's own — its builder, its renderer, its MCP endpoint — which serve first-party
+* traffic for every space and are therefore valid destinations for any token, whatever domains it declares. They are
+* passed in rather than read from configuration here because only the deployment knows what it runs.
+*/
+var domainAllowed = (host, origins, platformHosts = []) => {
+	if (origins.includes("*")) return true;
+	const hostname = hostnameOf(host);
+	if (!hostname) return false;
+	return [...platformHosts.map(hostnameOf), ...origins.map(hostnameOf)].filter(Boolean).includes(hostname);
+};
+/**
+* User input arrives as whatever someone typed — `example.com`, `https://example.com/`, `HTTPS://Example.com/x`. It
+* is stored as a canonical origin so the signed claim, the stored column and the comparison all agree.
+*/
+var normalizeDomain = (value) => {
+	const trimmed = value.trim();
+	if (trimmed === "*") return "*";
+	if (!hostnameOf(trimmed)) return;
+	try {
+		const url = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return;
+	}
+};
+/**
+* Who may put this space in an iframe, as CSP `frame-ancestors` sources.
+*
+* The deployment's own hosts are the floor — a builder previews every space in one — and a space widens it with the
+* domains its owner declared. `*` opts out entirely. Without this a published space is framable from any site on the
+* web, which is how one customer wraps another's space inside their own page and passes it off as theirs.
+*
+* Unlike the token's domain binding, this one is enforced by the browser, which is why it is worth stating even
+* though a determined caller can ignore the header: it stops the attack that needs a real visitor's browser.
+*/
+var frameAncestors = (declared, platformHosts = []) => {
+	if (declared.includes("*")) return ["*"];
+	return [.../* @__PURE__ */ new Set([
+		"'self'",
+		...platformHosts,
+		...declared
+	])];
+};
+/**
+* Which origins a request bearing this grant may be answered for.
+*
+* A space is reachable from the origins its own token declares, plus this deployment's own apps; `*` means anywhere,
+* and a grant that declares nothing at all falls back to the deployment's own unless it allows anonymous origins.
+* Returning `true` means "reflect whatever asked", which is what a CORS layer wants for the wildcard case.
+*/
+var corsOrigins = (declared, platformOrigins = [], allowWithoutOrigin = false) => {
+	const origins = declared ?? [];
+	if (origins.includes("*") || origins.length === 0 && allowWithoutOrigin) return true;
+	return [.../* @__PURE__ */ new Set([...platformOrigins, ...origins])];
+};
+//#endregion
+export { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain };

package/dist/core/auth/identity.d.ts

@@ -0,0 +1,108 @@
+import { CredentialCarrier } from './credentials';
+import { AuthFailure, SpaceScope, Tokens } from './tokens';
+/** A Plitzi-style account, as whatever stores accounts reports it. `permissions` are its GLOBAL capabilities. */
+export interface Actor {
+    id: number;
+    username: string;
+    email: string;
+    verified: boolean;
+    roles: string[];
+    permissions: string[];
+    token: string;
+    /** Unix seconds the presented credential dies at, off the stored row rather than the claim. */
+    expiresAt: number;
+}
+/** A space token, resolved. `userId` is set for `agent` grants and names the member who consented. */
+export interface Grant {
+    spaceId: number;
+    scope: SpaceScope;
+    userId?: number;
+    origins: string[];
+}
+/** What an account may do inside ONE space. */
+export interface SpaceMembership {
+    spaceId: number;
+    isOwner: boolean;
+    role: string;
+    permissions: string[];
+}
+/** The stored side of a space token — the row that makes a signature revocable. */
+export interface StoredSpaceToken {
+    spaceId: number;
+    scope: SpaceScope;
+    userId?: number;
+}
+/**
+ * What identity resolution cannot work out on its own: where accounts, space tokens and memberships are kept. This
+ * is the whole database surface authorization needs, and the reason a deployment can bring any store it likes.
+ */
+export interface IdentityAdapters {
+    /**
+     * The account a session token belongs to, looked up **by the token**. The row is the revocation switch: issuing a
+     * new session overwrites it, which is what makes rotation effective, so a token that no longer matches a row is
+     * revoked however valid its signature still is.
+     */
+    findAccountByToken: (token: string) => Promise<Actor | undefined>;
+    /**
+     * The stored space token. No row, no grant — which is also what its absence means: a deployment that serves only
+     * its own pages issues no space credentials, and omitting this refuses every grant instead of forcing a stub that
+     * returns undefined.
+     */
+    findSpaceToken?: (token: string) => Promise<StoredSpaceToken | undefined>;
+    /** Membership of one space. Without it, every space-level permission check refuses. */
+    findMembership?: (userId: number, spaceId: number) => Promise<SpaceMembership | undefined>;
+}
+export interface IdentityConfig {
+    /** This deployment's own hosts, which serve first-party traffic for every space. */
+    platformHosts?: string[];
+    /** Origins always accepted regardless of what a token declares — the deployment's own apps. */
+    platformOrigins?: string[];
+    /** Whether a request with no `Origin` at all may carry a space token. */
+    allowWithoutOrigin?: boolean;
+    log?: (message: string, meta: Record<string, unknown>) => void;
+}
+export type ActorResult = {
+    ok: true;
+    actor: Actor;
+} | {
+    ok: false;
+    reason: AuthFailure;
+};
+export type GrantResult = {
+    ok: true;
+    grant: Grant;
+} | {
+    ok: false;
+    reason: AuthFailure;
+};
+export interface GrantOptions {
+    /**
+     * Skips the Origin/embed check. Correct for non-browser transports (MCP, analytics ingest, WS upgrade). It does
+     * NOT skip the domain binding below — that one is the point.
+     */
+    skipOrigin?: boolean;
+    /**
+     * The host the request actually arrived on. A render token is only valid on the domains it declares, and unlike
+     * `Origin` the host cannot be chosen by the caller — it is where the request was routed.
+     */
+    host?: string;
+}
+export interface Carriers {
+    userTokenCandidates: (carrier: CredentialCarrier) => string[];
+    spaceTokenCandidates: (carrier: CredentialCarrier) => string[];
+}
+export declare const createIdentity: ({ tokens, carriers, adapters, config, presentedOrigin }: {
+    tokens: Tokens;
+    carriers: Carriers;
+    adapters: IdentityAdapters;
+    config?: IdentityConfig;
+    presentedOrigin: (carrier: CredentialCarrier) => string;
+}) => {
+    resolveActor: (carrier: CredentialCarrier) => Promise<ActorResult>;
+    resolveActorFromToken: (token: string) => Promise<ActorResult>;
+    resolveGrant: (carrier: CredentialCarrier, options?: GrantOptions) => Promise<GrantResult>;
+    resolveGrantFromToken: (token: string, origin: string, { skipOrigin, host }?: GrantOptions) => Promise<GrantResult>;
+    can: (actor: Actor, spaceId: number, permission: string) => Promise<boolean>;
+    grantCan: (grant: Grant, permission: string) => Promise<boolean>;
+};
+export type Identity = ReturnType<typeof createIdentity>;