@spfn/auth 0.3.0-beta.23 → 0.3.0-beta.25

package/dist/{session-Dfwu5g2W.d.ts → session-BbhAGZtA.d.ts}

@@ -1,4 +1,4 @@
-import { K as KeyAlgorithmType } from './types-DYyhze28.js';
+import { K as KeyAlgorithmType, S as SessionBindingType } from './types-CTdoTOxM.js';
 
 /**
  * @spfn/auth - Return-path validation
@@ -27,6 +27,35 @@ import { K as KeyAlgorithmType } from './types-DYyhze28.js';
  */
 declare function isSafeReturnPath(returnPath: string): boolean;
 
+/**
+ * The browser family a `user-agent` names — five badges, and nothing else.
+ *
+ * A bound session records the family it was sealed from and the Next.js proxy
+ * compares every later request against it (#97). The comparison has to be coarse
+ * on purpose: a version bump, a minor-version reduction, a platform token that
+ * changes when someone taps "Request desktop site" must all still be the same
+ * browser, or the check signs people out for ordinary acts instead of catching
+ * the cookie that moved to another machine.
+ *
+ * A fixed table rather than a parsing dependency. `package.json` carries no
+ * user-agent parser and adding one to answer a five-valued question would be out
+ * of proportion; the table below is the whole of what this package needs to know
+ * about user-agent strings.
+ *
+ * @module server/lib/ua-family
+ */
+/**
+ * The five answers, and deliberately no sixth.
+ *
+ * There is no desktop/mobile axis. Android's "Request desktop site" flips the
+ * platform token on the same browser in the same cookie jar, and a session that
+ * refused after that would be a support ticket for a thing the user did on
+ * purpose. What this check is looking for is a cookie that moved to a *different*
+ * browser, and the browser is what the badge names.
+ */
+declare const UA_FAMILIES: readonly ["edge", "chrome", "firefox", "safari", "other"];
+type UaFamily = typeof UA_FAMILIES[number];
+
 /**
  * @spfn/auth - Client Session Management
  *
@@ -34,11 +63,38 @@ declare function isSafeReturnPath(returnPath: string): boolean;
  * More efficient than Iron Session with better Edge Runtime support
  */
 
+/**
+ * What the sealed cookie carries.
+ *
+ * The first four fields are the session itself and have always been here. The
+ * last three are what #97 added, and all three are optional together: a cookie
+ * without them is an unbound session, which is every session an account that did
+ * not opt in gets and every session an app seals by hand with `saveSession()`.
+ * The proxy reads their absence as "behave exactly as before".
+ */
 interface SessionData {
     userId: string;
     privateKey: string;
     keyId: string;
     algorithm: KeyAlgorithmType;
+    /**
+     * `'passkey'` when the key sealed here is bound.
+     *
+     * The backend is the only party that knows an account opted in — the proxy
+     * generated the key but never saw the setting — so this is copied out of the
+     * `LoginResult` the sign-in answered with. Absent means unbound.
+     */
+    binding?: SessionBindingType;
+    /** Epoch milliseconds the bound key expires at. Only set alongside `binding`. */
+    keyExpiresAt?: number;
+    /**
+     * Browser family the session was sealed from, per `uaFamily`.
+     *
+     * Recorded here rather than read off the key row because the comparison
+     * happens in the proxy: it is the only hop that sees the browser's own
+     * `user-agent`, and a server component's call to the RPC proxy carries none.
+     */
+    uaFamily?: UaFamily;
 }
 /**
  * Seal session data into encrypted JWT (JWE)

package/dist/{types-DYyhze28.d.ts → types-CTdoTOxM.d.ts}

@@ -28,6 +28,29 @@ declare const KEY_PLATFORM: readonly ["ios", "android", "web", "desktop"];
 type KeyPlatformType = typeof KEY_PLATFORM[number];
 /** Longest device label accepted at registration, and what the list returns. */
 declare const KEY_DEVICE_NAME_MAX_LENGTH = 64;
+/**
+ * Whether a session's device key is tied to something that cannot be copied out
+ * of the browser.
+ *
+ * `'none'` is every session this package issued before #97: a key that lives
+ * ninety days, sealed inside the cookie, so a copy of that cookie signs exactly
+ * as the original does for as long as the key lasts. `'passkey'` is the opt-in —
+ * a key that lives hours instead, which only a fresh WebAuthn assertion may
+ * replace, so the copy stops working at the first renewal.
+ *
+ * The same two values name the account setting (`users.session_binding`) and the
+ * fact recorded on one key row (`user_public_keys.binding`). They are one list
+ * because a key is bound exactly when the account that owns it asked for it, and
+ * a second vocabulary would only invite the two to drift.
+ *
+ * Server-decided, always. Nothing on a request body chooses it — see
+ * `registerPublicKeyService`.
+ */
+declare const SESSION_BINDINGS: readonly ["none", "passkey"];
+/**
+ * Session binding type derived from the const array
+ */
+type SessionBindingType = typeof SESSION_BINDINGS[number];
 /**
  * Invitation status enum values
  * Single source of truth for all invitation statuses
@@ -95,4 +118,4 @@ declare const PURGE_STRATEGIES: readonly ["anonymize", "hard-delete"];
  */
 type PurgeStrategy = typeof PURGE_STRATEGIES[number];
 
-export { ACCOUNT_DELETION_REQUESTED_BY as A, INVITATION_STATUSES as I, type KeyAlgorithmType as K, PURGE_STRATEGIES as P, SOCIAL_PROVIDERS as S, USER_STATUSES as U, ACCOUNT_DELETION_REQUEST_STATUSES as a, type AccountDeletionRequestStatus as b, type AccountDeletionRequestedBy as c, type InvitationStatus as d, KEY_ALGORITHM as e, KEY_DEVICE_NAME_MAX_LENGTH as f, KEY_PLATFORM as g, type KeyPlatformType as h, type PurgeStrategy as i, type SocialProvider as j, type UserStatus as k };
+export { ACCOUNT_DELETION_REQUESTED_BY as A, INVITATION_STATUSES as I, type KeyAlgorithmType as K, PURGE_STRATEGIES as P, type SessionBindingType as S, USER_STATUSES as U, ACCOUNT_DELETION_REQUEST_STATUSES as a, type AccountDeletionRequestStatus as b, type AccountDeletionRequestedBy as c, type InvitationStatus as d, KEY_ALGORITHM as e, KEY_DEVICE_NAME_MAX_LENGTH as f, KEY_PLATFORM as g, type KeyPlatformType as h, type PurgeStrategy as i, SESSION_BINDINGS as j, SOCIAL_PROVIDERS as k, type SocialProvider as l, type UserStatus as m };

package/migrations/20260918184037_happy_mordo/migration.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "spfn_auth"."users" ADD COLUMN "session_binding" text DEFAULT 'none' NOT NULL;--> statement-breakpoint
+ALTER TABLE "spfn_auth"."users" ADD COLUMN "session_binding_changed_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "spfn_auth"."user_public_keys" ADD COLUMN "registered_ua_family" text;--> statement-breakpoint
+ALTER TABLE "spfn_auth"."user_public_keys" ADD COLUMN "binding" text DEFAULT 'none' NOT NULL;