@plitzi/sdk-server 0.33.2 → 0.34.0

package/dist/adapters/space/types.d.ts

@@ -0,0 +1,64 @@
+import { Environment, PluginSource, SSRCredential, SSRRequest, SSRTemplateProps } from '@plitzi/sdk-shared';
+/**
+ * Which space a request resolved to, before the server fills in what is the same for everybody.
+ *
+ * `SSRSpaceDeployment` minus the parts a resolver has no business deciding: `frameAncestors` is derived from the
+ * space's declared domains by one rule, and `error` is what a REFUSAL is, which is a different return.
+ */
+export interface SpaceResolution {
+    spaceId: number;
+    /** Defaults to `main`. */
+    environment?: Environment;
+    /** Defaults to `0` — the live snapshot. */
+    revision?: number;
+    credential?: SSRCredential;
+    /**
+     * This render is an author looking at their own work rather than a visitor being served. Metering skips it.
+     * `authoringPreview` sets it; nothing infers it, because only the resolver can tell the two apart.
+     */
+    authoring?: boolean;
+    templateProps?: SSRTemplateProps;
+    pluginNames?: string[];
+    pluginSources?: Record<string, PluginSource>;
+}
+/** A resolver that has decided this request gets nothing, and that no later resolver should be asked. */
+export interface SpaceRefusal {
+    refuse: {
+        code: number;
+        message: string;
+    };
+}
+/**
+ * One way a request becomes a space.
+ *
+ * Three returns, and the difference between two of them is the whole reason this is a list:
+ *
+ * - a `SpaceResolution` — mine, here it is;
+ * - a `SpaceRefusal` — mine, and the answer is no. **The chain stops.** A request that presented a bad credential
+ *   for a space must not fall through to being served as an anonymous visitor of some other one;
+ * - `undefined` — not mine, ask the next.
+ */
+export type SpaceResolver = (req: SSRRequest) => Promise<SpaceResolution | SpaceRefusal | undefined>;
+/**
+ * Somewhere to keep a lookup that every request repeats. Strings in, strings out: JSON is this module's problem,
+ * and a `get`/`set`/`delete` of strings is satisfied by Redis, Memcached, a file, or the in-memory cache below —
+ * without any of them being named here.
+ *
+ * Every method may fail without failing the request: a cache that is down is a slow deployment, not a broken one.
+ */
+export interface SpaceCache {
+    get: (key: string) => Promise<string | undefined>;
+    set: (key: string, value: string, ttlSeconds: number) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+}
+export declare const isRefusal: (value: SpaceResolution | SpaceRefusal) => value is SpaceRefusal;
+/** A resolver's refusal, as the one-liner it deserves to be at a call site. */
+export declare const refuse: (code: number, message: string) => SpaceRefusal;
+/**
+ * A cache in this process's memory, for a deployment that runs one.
+ *
+ * Say that out loud before using it: each process keeps its own, so invalidating on one does not invalidate on the
+ * others, and a deployment behind more than one replica will serve a stale resolution from the replicas that were
+ * not told. That is fine for a single-process server and wrong for a cluster, which wants Redis or nothing.
+ */
+export declare const createMemoryCache: () => SpaceCache;

package/dist/adapters/space/types.js

@@ -0,0 +1,41 @@
+//#region src/adapters/space/types.ts
+var isRefusal = (value) => "refuse" in value;
+/** A resolver's refusal, as the one-liner it deserves to be at a call site. */
+var refuse = (code, message) => ({ refuse: {
+	code,
+	message
+} });
+/**
+* A cache in this process's memory, for a deployment that runs one.
+*
+* Say that out loud before using it: each process keeps its own, so invalidating on one does not invalidate on the
+* others, and a deployment behind more than one replica will serve a stale resolution from the replicas that were
+* not told. That is fine for a single-process server and wrong for a cluster, which wants Redis or nothing.
+*/
+var createMemoryCache = () => {
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => {
+			const entry = entries.get(key);
+			if (!entry) return Promise.resolve(void 0);
+			if (Date.now() > entry.expiresAt) {
+				entries.delete(key);
+				return Promise.resolve(void 0);
+			}
+			return Promise.resolve(entry.value);
+		},
+		set: (key, value, ttlSeconds) => {
+			entries.set(key, {
+				value,
+				expiresAt: Date.now() + ttlSeconds * 1e3
+			});
+			return Promise.resolve();
+		},
+		delete: (key) => {
+			entries.delete(key);
+			return Promise.resolve();
+		}
+	};
+};
+//#endregion
+export { createMemoryCache, isRefusal, refuse };

package/dist/auth.d.ts

@@ -0,0 +1,50 @@
+/** Authentication and authorization, whole. Import it as `@plitzi/sdk-server/auth`.
+ *
+ *  Everything a deployment needs to answer *who is this* and *may they* — the token kernel, the session cookies,
+ *  the identity resolver, the RBAC checks, the `/auth` flows, the OAuth providers and the space-token lifecycle.
+ *  `createAuth` assembles the lot in one call and is what almost every deployment wants; the pieces stay exported
+ *  for the one that needs to build a half of it itself.
+ *
+ *  This used to live in `@plitzi/sdk-server/kernel`, next to the HTTP dispatcher. Two unrelated surfaces under one
+ *  name that named neither of them: a deployment wiring up sessions had no reason to read about stages, and
+ *  `@plitzi/sdk-mcp`, which wants the dispatcher and no auth at all, had to import from the same place. `/kernel`
+ *  is now the HTTP kernel and nothing else.
+ *
+ *  ```ts
+ *  import { createAuth } from '@plitzi/sdk-server/auth';
+ *  import { createServer } from '@plitzi/sdk-server';
+ *
+ *  const auth = createAuth({ tokens: { secret, issuer }, adapters: myAccountStore });
+ *  const server = createServer({ adapters: space, auth });
+ *  ```
+ *
+ *  A deployment with no account store of its own can have one: `@plitzi/sdk-server/mysql` brings the tables and
+ *  every adapter below already implemented. */
+export { createAuth } from './core/auth/createAuth';
+export { createAuthApi } from './core/auth/api';
+export { createCsrf, csrfFailureMessage } from './core/auth/csrf';
+export { createAuthorizer, checkPermission, checkSpaceAccess, requirementFor } from './core/auth/authorize';
+export { createCarriers, presentedOrigin } from './core/auth/credentials';
+export { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from './core/auth/domains';
+export { createIdentity } from './core/auth/identity';
+export { generateToken, hashPassword, verifyPassword } from './core/auth/passwords';
+export { BUILT_IN_PROVIDERS, OAuthFailure, createSocialAuth, requestProfileJson } from './core/auth/oauth';
+export { createRedirectPolicy } from './core/auth/redirects';
+export type { RedirectPolicyConfig } from './core/auth/redirects';
+export { applySessionOutcome, authPolicyRules, authRoutes } from './core/auth/routes';
+export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from './core/auth/session';
+export { createMemoryRateLimit } from './core/auth/throttle';
+export { createSpaceTokenApi } from './core/auth/spaceTokens';
+export { SCOPES, authFailureMessage, createTokens, userIdOf } from './core/auth/tokens';
+export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpUri, verifyTotp } from './core/auth/totp';
+export type { Auth, AuthConfig } from './core/auth/createAuth';
+export type { AccountAccess, AccountAdapters, AccountQuery, AccountRecord, AccountStatus, AuthApi, AuthApiConfig, AuthOutcome, ExchangeResult, MfaRecord, PasswordPolicy, SecurityEvent, SessionClient, SessionContext, SessionSummary, ThrottleAttempt, ThrottledAction } from './core/auth/api';
+export type { AuthPolicy, AuthorizeResult, Authorizer, MembershipFacts, PathMatcher, PermissionCheck, Requirement, SpaceAccessCheck } from './core/auth/authorize';
+export type { CredentialCarrier } from './core/auth/credentials';
+export type { Csrf, CsrfCarrier, CsrfConfig, CsrfFailure, CsrfResult, CsrfSubject } from './core/auth/csrf';
+export type { Actor, ActorResult, Grant, GrantOptions, GrantResult, Identity, IdentityAdapters, IdentityConfig, SpaceMembership, StoredSpaceToken } from './core/auth/identity';
+export type { CompletedFlow, OAuthFailureReason, OAuthProfile, OAuthProvider, OAuthProviderConfig, SocialAuth, SocialAuthAdapters, SocialAuthConfig, StartedFlow } from './core/auth/oauth';
+export type { AuthRequest, AuthRoute } from './core/auth/routes';
+export type { CookieCarrier, CookieSink, SessionCookieParams, SessionCookies } from './core/auth/session';
+export type { SpaceTokenAdapters, SpaceTokenApi, SpaceTokenContext, SpaceTokenOutcome, SpaceTokenRecord, SpaceTokenSummary } from './core/auth/spaceTokens';
+export type { AuthFailure, MfaChallengePayload, RefreshTokenPayload, SpaceScope, SpaceTokenOptions, SpaceTokenPayload, TokenConfig, TokenScope, Tokens, UserTokenOptions, UserTokenPayload, VerifyResult, WidgetTokenPayload } from './core/auth/tokens';

package/dist/auth.js

@@ -0,0 +1,19 @@
+import { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from "./core/auth/session.js";
+import { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from "./core/auth/domains.js";
+import { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor } from "./core/auth/authorize.js";
+import { generateToken, hashPassword, verifyPassword } from "./core/auth/passwords.js";
+import { createMemoryRateLimit } from "./core/auth/throttle.js";
+import { SCOPES, authFailureMessage, createTokens, userIdOf } from "./core/auth/tokens.js";
+import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpUri, verifyTotp } from "./core/auth/totp.js";
+import { createAuthApi } from "./core/auth/api.js";
+import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
+import { createCsrf, csrfFailureMessage } from "./core/auth/csrf.js";
+import { createIdentity } from "./core/auth/identity.js";
+import { applySessionOutcome, authPolicyRules, authRoutes } from "./core/auth/routes.js";
+import { createAuth } from "./core/auth/createAuth.js";
+import { OAuthFailure } from "./core/auth/oauth/types.js";
+import { requestProfileJson } from "./core/auth/oauth/client.js";
+import { createRedirectPolicy } from "./core/auth/redirects.js";
+import { BUILT_IN_PROVIDERS, createSocialAuth } from "./core/auth/oauth/index.js";
+import { createSpaceTokenApi } from "./core/auth/spaceTokens.js";
+export { ANY_DOMAIN, BUILT_IN_PROVIDERS, OAuthFailure, SCOPES, appendCookies, applySessionOutcome, authFailureMessage, authPolicyRules, authRoutes, checkPermission, checkSpaceAccess, clearFlowCookie, clearSessionCookies, corsOrigins, createAuth, createAuthApi, createAuthorizer, createCarriers, createCsrf, createIdentity, createMemoryRateLimit, createRedirectPolicy, createSessionCookies, createSocialAuth, createSpaceTokenApi, createTokens, csrfFailureMessage, domainAllowed, frameAncestors, generateRecoveryCodes, generateToken, generateTotpSecret, hashPassword, hostnameOf, isLocalHost, normalizeDomain, normalizeRecoveryCode, presentedOrigin, randomCode, readFlowCookie, readRefreshToken, readSessionToken, requestProfileJson, requirementFor, sessionCookieParams, sessionHintValue, totpCode, totpUri, userIdOf, verifyPassword, verifyTotp, writeFlowCookie, writeSessionCookies };