@wtfalch/auth 0.4.1 → 0.6.0

package/dist/sessions.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Server-side records behind namespace sessions.
+ *
+ * The browser holds a sealed handle that never changes after sign-in; the
+ * tokens live here. That is what makes three things possible that a sealed
+ * token cookie cannot do: a logout that also kills copies of the cookie, a
+ * refresh that no late response can undo by setting an older cookie, and two
+ * replicas refreshing the same session without logging the person out.
+ *
+ * The store is the app's. It sees a digest of the handle, never the handle,
+ * and tokens sealed with the app's cookie secret, never the tokens.
+ */
+export interface SessionRecord {
+    /** SHA-256 of the handle, base64url. */
+    key: string;
+    /** Digest of the namespace binding and revision the session was made under. */
+    context: string;
+    /** The issuer's user id. */
+    subject: string;
+    /** Bumped by every write. `advance` only succeeds from the current value. */
+    generation: number;
+    /**
+     * Unix seconds until which one request holds the right to refresh, or null.
+     * The issuer rotates refresh tokens, so two replicas refreshing at once
+     * would spend the same token and one would be refused. The lease is how
+     * exactly one of them asks.
+     */
+    leaseUntil: number | null;
+    /** The tokens, sealed by the SDK. Opaque here. */
+    payload: string;
+    /** Unix seconds. Slides forward on every refresh. */
+    expiresAt: number;
+    /** Unix seconds, or null while the session is live. */
+    revokedAt: number | null;
+}
+export type SessionUpdate = Pick<SessionRecord, 'payload' | 'expiresAt' | 'leaseUntil'>;
+export interface SessionStore {
+    create(record: SessionRecord): Promise<void>;
+    get(key: string): Promise<SessionRecord | null>;
+    /**
+     * Replace the payload, expiry and lease, and bump the generation, only if the
+     * record is still at `generation` and not revoked. Resolves whether it did.
+     */
+    advance(key: string, generation: number, next: SessionUpdate): Promise<boolean>;
+    revoke(key: string, at: number): Promise<void>;
+    /** Revoke every live record for this subject under this binding context. Resolves how many. */
+    revokeSubject(context: string, subject: string, at: number): Promise<number>;
+}
+/**
+ * One process only. For tests and a single-instance development server: two
+ * replicas with separate memory stores do not share revocations.
+ */
+export declare function createMemorySessionStore(): SessionStore;
+/** The table `createPostgresSessionStore` expects. Run it in the app's own migrations. */
+export declare const POSTGRES_SESSION_TABLE = "create table if not exists wtfalch_auth_sessions (\n  key text primary key,\n  context text not null,\n  subject text not null,\n  generation integer not null,\n  payload text not null,\n  expires_at bigint not null,\n  lease_until bigint,\n  revoked_at bigint\n);\ncreate index if not exists wtfalch_auth_sessions_subject on wtfalch_auth_sessions (context, subject);\ncreate index if not exists wtfalch_auth_sessions_expiry on wtfalch_auth_sessions (expires_at);";
+type Row = Record<string, unknown>;
+/**
+ * Postgres through whatever driver the app already has. `query` runs one
+ * parameterised statement and resolves its rows:
+ *
+ * - node-postgres: `(text, values) => pool.query(text, values).then((r) => r.rows)`
+ * - postgres.js: `(text, values) => sql.unsafe(text, values)`
+ *
+ * Expired rows are removed a few at a time on each sign-in.
+ */
+export declare function createPostgresSessionStore(input: {
+    query: (text: string, values: unknown[]) => Promise<Row[]>;
+}): SessionStore;
+export {};

package/dist/sessions.js

@@ -0,0 +1,119 @@
+/**
+ * One process only. For tests and a single-instance development server: two
+ * replicas with separate memory stores do not share revocations.
+ */
+export function createMemorySessionStore() {
+    const records = new Map();
+    const sweep = (now) => {
+        for (const [key, record] of records)
+            if (record.expiresAt <= now)
+                records.delete(key);
+    };
+    return {
+        async create(record) {
+            sweep(Math.floor(Date.now() / 1000));
+            if (records.has(record.key))
+                throw new Error('session record already exists');
+            records.set(record.key, { ...record });
+        },
+        async get(key) {
+            const record = records.get(key);
+            return record ? { ...record } : null;
+        },
+        async advance(key, generation, next) {
+            const record = records.get(key);
+            if (!record || record.revokedAt !== null || record.generation !== generation)
+                return false;
+            records.set(key, { ...record, ...next, generation: generation + 1 });
+            return true;
+        },
+        async revoke(key, at) {
+            const record = records.get(key);
+            if (record && record.revokedAt === null)
+                record.revokedAt = at;
+        },
+        async revokeSubject(context, subject, at) {
+            let count = 0;
+            for (const record of records.values())
+                if (record.context === context && record.subject === subject && record.revokedAt === null) {
+                    record.revokedAt = at;
+                    count++;
+                }
+            return count;
+        },
+    };
+}
+/** The table `createPostgresSessionStore` expects. Run it in the app's own migrations. */
+export const POSTGRES_SESSION_TABLE = `create table if not exists wtfalch_auth_sessions (
+  key text primary key,
+  context text not null,
+  subject text not null,
+  generation integer not null,
+  payload text not null,
+  expires_at bigint not null,
+  lease_until bigint,
+  revoked_at bigint
+);
+create index if not exists wtfalch_auth_sessions_subject on wtfalch_auth_sessions (context, subject);
+create index if not exists wtfalch_auth_sessions_expiry on wtfalch_auth_sessions (expires_at);`;
+const nullable = (value) => value === null || value === undefined ? null : Number(value);
+/**
+ * Postgres through whatever driver the app already has. `query` runs one
+ * parameterised statement and resolves its rows:
+ *
+ * - node-postgres: `(text, values) => pool.query(text, values).then((r) => r.rows)`
+ * - postgres.js: `(text, values) => sql.unsafe(text, values)`
+ *
+ * Expired rows are removed a few at a time on each sign-in.
+ */
+export function createPostgresSessionStore(input) {
+    const { query } = input;
+    const record = (row) => ({
+        key: String(row.key),
+        context: String(row.context),
+        subject: String(row.subject),
+        generation: Number(row.generation),
+        payload: String(row.payload),
+        expiresAt: Number(row.expires_at),
+        leaseUntil: nullable(row.lease_until),
+        revokedAt: nullable(row.revoked_at),
+    });
+    return {
+        async create(r) {
+            await query(`delete from wtfalch_auth_sessions where key in
+           (select key from wtfalch_auth_sessions where expires_at <= $1 limit 100)`, [Math.floor(Date.now() / 1000)]);
+            await query(`insert into wtfalch_auth_sessions
+           (key, context, subject, generation, payload, expires_at, lease_until, revoked_at)
+         values ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+                r.key,
+                r.context,
+                r.subject,
+                r.generation,
+                r.payload,
+                r.expiresAt,
+                r.leaseUntil,
+                r.revokedAt,
+            ]);
+        },
+        async get(key) {
+            const rows = await query('select * from wtfalch_auth_sessions where key = $1', [key]);
+            return rows[0] ? record(rows[0]) : null;
+        },
+        async advance(key, generation, next) {
+            const rows = await query(`update wtfalch_auth_sessions
+            set payload = $3, expires_at = $4, lease_until = $5, generation = generation + 1
+          where key = $1 and generation = $2 and revoked_at is null
+          returning key`, [key, generation, next.payload, next.expiresAt, next.leaseUntil]);
+            return rows.length === 1;
+        },
+        async revoke(key, at) {
+            await query('update wtfalch_auth_sessions set revoked_at = $2 where key = $1 and revoked_at is null', [key, at]);
+        },
+        async revokeSubject(context, subject, at) {
+            const rows = await query(`update wtfalch_auth_sessions set revoked_at = $3
+          where context = $1 and subject = $2 and revoked_at is null
+          returning key`, [context, subject, at]);
+            return rows.length;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Sign in against auth.wtfalch.dev: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",
@@ -21,6 +21,18 @@
     "./browser": {
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
+    },
+    "./namespaces": {
+      "types": "./dist/namespaces.d.ts",
+      "default": "./dist/namespaces.js"
+    },
+    "./namespace-server": {
+      "types": "./dist/namespace-server.d.ts",
+      "default": "./dist/namespace-server.js"
+    },
+    "./sessions": {
+      "types": "./dist/sessions.d.ts",
+      "default": "./dist/sessions.js"
     }
   },
   "sideEffects": false,
@@ -46,6 +58,7 @@
     }
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
     "@types/react": "^19",
     "@wtfalch/auth-broker": "workspace:*",