@voltro/plugin-auth 0.1.0

package/dist/plugin.d.ts

@@ -0,0 +1,351 @@
+import { AuthStrategy } from '@voltro/protocol';
+import { Effect } from 'effect';
+import { SessionSecrets } from '@voltro/protocol/session';
+import { Subject } from '@voltro/protocol';
+import { VoidIfEmpty } from 'effect/Types';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+declare interface AuthConfig {
+    readonly secret: string;
+    /** Explicit keyed secret set for zero-downtime rotation. When absent,
+     *  the set is derived from `secret` (current) + the
+     *  `VOLTRO_SESSION_SECRET_PREVIOUS` / `VOLTRO_SESSION_KID*` env vars —
+     *  so env-var rotation works without setting this. Cookies are always
+     *  SIGNED with the current key; verification also accepts `previous`. */
+    readonly secrets?: SessionSecrets;
+    readonly defaultTenantId: string;
+    readonly cookieDomain?: string;
+    readonly cookieSecure?: boolean;
+    /** Where to redirect on successful sign-in / sign-up. Default: '/'. */
+    readonly successRedirect?: string;
+    /** Injected email transport for magic-link + password-reset. When
+     *  absent, those handlers still mint + persist the token but cannot
+     *  deliver it (they return 202 so existence isn't leaked). The
+     *  documented default forwards to `@voltro/plugin-mail` via
+     *  `mailSender(mailService)`. */
+    readonly sendEmail?: SendEmail;
+    /** Absolute base URL used to build the links inside emails, e.g.
+     *  `https://app.example.com`. Defaults to '' (relative links). */
+    readonly appBaseUrl?: string;
+    /** Post-authentication subject guards. After a login path resolves the
+     *  authenticated user (credentials verified) but BEFORE a session is
+     *  issued, every guard runs against that `UserRecord`; the first to veto
+     *  (`{ ok: false }`) aborts the login with a 403 carrying its `code` and
+     *  NO session cookie. General-purpose: `@voltro/plugin-deactivation`'s
+     *  `deactivationGuard()` is the canonical one ("account deactivated"),
+     *  but any concern (unverified email, suspended tenant, …) can hook here.
+     *  Absent / empty ⇒ every authenticated user proceeds unchanged. */
+    readonly subjectGuards?: ReadonlyArray<SubjectGuard>;
+}
+
+/**
+ * The auth plugin instance also carries a pre-wired session
+ * `AuthStrategy` (keyed verify + the SAME revocation cache the HTTP
+ * routes use) so the framework's serve pipeline can slot it into the
+ * per-app auth chain — the rpc/WS path then rejects revoked sessions
+ * exactly like the `/auth/*` routes. Read it via
+ * `getAuthSessionStrategy`.
+ */
+export declare interface AuthPlugin extends VoltroPlugin {
+    readonly auth: {
+        readonly sessionStrategy: AuthStrategy;
+    };
+}
+
+export declare const authRoutesPlugin: (options: AuthRoutesPluginOptions) => AuthPlugin;
+
+export declare interface AuthRoutesPluginOptions extends AuthConfig {
+    /** The user store backing every handler. */
+    readonly store: UserStore;
+    /** Passkey config — when omitted, the four passkey routes return 501. */
+    readonly passkey?: PasskeyConfig;
+    /** Challenge store for the passkey ceremonies. Defaults to an in-memory
+     *  single-node store. */
+    readonly challengeStore?: ChallengeStore;
+    /** MFA (TOTP) enrolment config. When set, the `/auth/mfa/enroll/*`
+     *  routes are mounted so an authenticated user can enrol a second
+     *  factor; `issuer` is the label shown in their authenticator app.
+     *  Sign-in enforcement (the `/auth/mfa/verify` challenge) is ALWAYS
+     *  active for enrolled users regardless of this — it only gates the
+     *  enrolment routes. */
+    readonly mfa?: MfaConfig;
+    /** Rebind hook for switch-tenant on the live WS path — pass
+     *  `bindConnectionSubject` from `@voltro/runtime`. */
+    readonly rebind?: RebindConnection;
+    /** Route prefix. Default `/auth`. */
+    readonly prefix?: string;
+    /** Tuning for the request-time session-revocation check (TTL cache
+     *  window, default 30s; `now` is a testing seam). */
+    readonly sessionRevocation?: SessionRevocationOptions;
+    /** Disambiguates multiple instances of this plugin in one app. */
+    readonly name?: string;
+}
+
+/** Single-use challenge storage. `key` is `<userId>:<ceremony>`. */
+declare interface ChallengeStore {
+    readonly put: (key: string, challenge: string, ttlSeconds: number) => Effect.Effect<void>;
+    /** Read AND delete (single-use). Returns null when absent/expired. */
+    readonly take: (key: string) => Effect.Effect<string | null>;
+}
+
+/**
+ * Pull the pre-wired session strategy off a plugin list (the framework's
+ * serve pipeline calls this when composing the auth chain). Returns the
+ * FIRST auth plugin's strategy, or null when no auth plugin is present.
+ */
+export declare const getAuthSessionStrategy: (plugins: ReadonlyArray<VoltroPlugin>) => AuthStrategy | null;
+
+/** One tenant a user belongs to. The active tenant lives on the Subject;
+ *  the full set drives the switch-tenant menu + the switch-tenant guard. */
+declare interface MembershipRecord {
+    readonly userId: string;
+    readonly tenantId: string;
+    readonly role: string;
+    readonly joinedAt: Date;
+}
+
+/** MFA (TOTP) enrolment config. */
+export declare interface MfaConfig {
+    /** Issuer label shown in the user's authenticator app (typically your
+     *  product name, e.g. "Voltro Cloud"). */
+    readonly issuer: string;
+}
+
+declare interface PasskeyConfig {
+    /** Relying-party id — the registrable domain (e.g. `example.com`). */
+    readonly rpId: string;
+    /** Human-readable RP name shown in the OS prompt. */
+    readonly rpName: string;
+    /** The exact origin ceremonies must run on (e.g. `https://app.example.com`). */
+    readonly origin: string;
+}
+
+/** A registered WebAuthn credential. */
+declare interface PasskeyRecord {
+    readonly id: string;
+    readonly credentialId: string;
+    readonly userId: string;
+    readonly publicKey: string;
+    readonly counter: number;
+    readonly transports?: string | null;
+    readonly createdAt: Date;
+    readonly lastUsedAt: Date | null;
+}
+
+/** Injected rebinder — the app passes `bindConnectionSubject` from
+ *  `@voltro/runtime` so the plugin stays runtime-agnostic. */
+declare type RebindConnection = (clientId: number, subject: ReturnType<typeof subjectFromUser>) => void;
+
+declare type SendEmail = (input: SendEmailInput) => Promise<void>;
+
+/** The email hook the plugin calls for magic-link + password-reset. Inject
+ *  it on the config. The documented default wiring forwards to
+ *  `@voltro/plugin-mail`'s `MailService.send` (see `mailSender`). */
+declare interface SendEmailInput {
+    readonly to: string;
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+    /** Discriminates the flow so a custom sender can branch. */
+    readonly kind: 'magic-link' | 'password-reset';
+    /** The action URL embedded in the email (also present inside `html`). */
+    readonly actionUrl: string;
+}
+
+/** A server-side session row — enumerated so apps can list active
+ *  devices + revoke them. Written on sign-in; deleted on revoke. */
+declare interface SessionRecord {
+    readonly id: string;
+    readonly userId: string;
+    readonly tenantId: string;
+    readonly expiresAt: Date;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+    readonly createdAt: Date;
+    readonly lastSeenAt: Date;
+}
+
+declare interface SessionRevocationOptions {
+    /** Cache window in milliseconds. A revocation performed elsewhere
+     *  takes effect on this process within this window. Default 30s.
+     *  `0` disables caching (every verify hits the store). */
+    readonly ttlMs?: number;
+    /** Upper bound on cached session ids. When exceeded, expired entries
+     *  are swept; if still over, the oldest entries are dropped. Default
+     *  10 000. */
+    readonly maxEntries?: number;
+    /** Clock override (epoch milliseconds). Defaults to `Date.now`. A
+     *  testing seam — lets suites cross the cache window without
+     *  wall-clock sleeps. */
+    readonly now?: () => number;
+}
+
+/**
+ * Convert a UserRecord into the protocol Subject the framework
+ * carries around per-request. Tenant id flows through; user type
+ * is locked to 'user'.
+ *
+ * The user's tenant memberships, when supplied, are carried in
+ * `metadata.memberships` (the protocol Subject's metadata slot — the
+ * framework never reads it, but app code + the switch-tenant menu do).
+ * Pass an explicit `tenantId` to make the ACTIVE tenant differ from the
+ * user's home tenant (post switch-tenant rebind).
+ */
+declare const subjectFromUser: (user: UserRecord, options?: {
+    readonly tenantId?: string;
+    readonly memberships?: ReadonlyArray<MembershipRecord>;
+}) => Subject;
+
+/**
+ * A post-authentication subject guard: given the authenticated user,
+ * decide whether the login may proceed. Runs after the credential check,
+ * before the session is issued. Effect-native so a guard can do IO (e.g.
+ * read a fresh flag) without a Promise bridge.
+ */
+declare type SubjectGuard = (user: UserRecord) => Effect.Effect<SubjectGuardVerdict>;
+
+/** A guard's decision. Allow, or reject with a stable machine `code`
+ *  (surfaced as the 403 body's `error`) plus a human `message`. */
+declare type SubjectGuardVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+
+declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending';
+
+/** A single-use, hashed, expiring token (magic-link / password-reset). */
+declare interface TokenRecord {
+    readonly id: string;
+    readonly tokenHash: string;
+    readonly userId: string;
+    readonly purpose: TokenPurpose;
+    readonly expiresAt: Date;
+    readonly consumedAt: Date | null;
+    readonly createdAt: Date;
+}
+
+declare class UserAlreadyExistsError extends UserAlreadyExistsError_base<{
+    readonly email: string;
+}> {
+}
+
+declare const UserAlreadyExistsError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "UserAlreadyExistsError";
+} & Readonly<A>;
+
+declare class UserNotFoundError extends UserNotFoundError_base<{
+    readonly userId: string;
+}> {
+}
+
+declare const UserNotFoundError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "UserNotFoundError";
+} & Readonly<A>;
+
+declare interface UserRecord {
+    readonly id: string;
+    readonly email: string;
+    readonly passwordHash: string;
+    readonly tenantId: string;
+    readonly createdAt: Date;
+    /** Base32-encoded TOTP secret. `null` = MFA not enrolled. Set by
+     *  `setMfaSecret()` from the enrolment handler. Stored as plaintext. */
+    readonly mfaSecret?: string | null;
+    /** Timestamp the user completed TOTP enrolment (first successful
+     *  verify). Distinct from the secret being set — a half-completed
+     *  enrolment leaves `mfaSecret` populated but this null. */
+    readonly mfaEnrolledAt?: Date | null;
+    /** Optional lifecycle flag read by post-authentication subject guards.
+     *  Set (a `Date`) means the account is DEACTIVATED — `@voltro/plugin-
+     *  deactivation`'s `deactivationGuard()` vetoes login when it's non-null.
+     *  `null` / absent means active. A store populates it from the app's
+     *  `deactivatedAt` column (added by the `deactivation()` mixin) when that
+     *  column exists; stores without the column simply leave it undefined and
+     *  the guard treats the account as active. */
+    readonly deactivatedAt?: Date | null;
+}
+
+declare interface UserStore {
+    readonly findByEmail: (email: string) => Effect.Effect<UserRecord | null>;
+    readonly findById: (id: string) => Effect.Effect<UserRecord | null>;
+    readonly insert: (user: Omit<UserRecord, 'createdAt'>) => Effect.Effect<UserRecord, UserAlreadyExistsError>;
+    /** Replace a user's stored password hash. Used by password-reset AND
+     *  by rehash-on-verify (silently upgrading an under-cost hash on a
+     *  successful sign-in). */
+    readonly updatePassword: (userId: string, newHash: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Stash a freshly-generated TOTP secret on the user. Called by
+     *  the MFA enrolment handler before the user verifies the first
+     *  code. */
+    readonly setMfaSecret: (userId: string, secret: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Mark MFA as fully enrolled (called after the first successful
+     *  TOTP verify completes the enrolment ceremony). */
+    readonly markMfaEnrolled: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Wipe the secret + enrolledAt. Used by /account/security's
+     *  "remove MFA" action. */
+    readonly clearMfa: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Every tenant the user belongs to. */
+    readonly listMemberships: (userId: string) => Effect.Effect<ReadonlyArray<MembershipRecord>>;
+    /** Idempotent grant: inserts the [userId, tenantId] membership or
+     *  updates its role if it already exists. The DB-level composite
+     *  UNIQUE on `[userId, tenantId]` (see `membershipsTable`) is the
+     *  source of truth; this upsert converges to it. */
+    readonly addMembership: (membership: Omit<MembershipRecord, 'joinedAt'>) => Effect.Effect<MembershipRecord>;
+    /** Resolve the role for a [userId, tenantId] pair, or null when the
+     *  user is NOT a member. The switch-tenant handler calls this to
+     *  validate the requested tenant before rebinding the connection. */
+    readonly membershipRole: (userId: string, tenantId: string) => Effect.Effect<string | null>;
+    /** Active sessions for a user (most recent first). */
+    readonly listSessions: (userId: string) => Effect.Effect<ReadonlyArray<SessionRecord>>;
+    /** Record a session on sign-in. */
+    readonly insertSession: (session: Omit<SessionRecord, 'createdAt' | 'lastSeenAt'>) => Effect.Effect<SessionRecord>;
+    /** Look up one session row by id. The request-time revocation check
+     *  (`makeSessionRevocationChecker`) calls this — a missing row means
+     *  the session was revoked. */
+    readonly findSession: (sessionId: string) => Effect.Effect<SessionRecord | null>;
+    /** Slide a session row forward: bump `expiresAt` + `lastSeenAt`. Called
+     *  when the sliding-window renewal re-issues the cookie, so the row
+     *  outlives the renewed cookie and the revocation check keeps passing. */
+    readonly touchSession: (sessionId: string, expiresAt: Date) => Effect.Effect<void>;
+    /** Revoke a single session — only if it belongs to `userId` (so a
+     *  caller can't revoke another user's session by id-guessing). Returns
+     *  whether a row was removed. */
+    readonly revokeSession: (userId: string, sessionId: string) => Effect.Effect<boolean>;
+    /** Revoke every session for the user EXCEPT `keepSessionId` — the
+     *  "sign out other devices" action. Returns the count removed. */
+    readonly revokeAllOtherSessions: (userId: string, keepSessionId: string) => Effect.Effect<number>;
+    /** Persist a single-use token (already hashed). */
+    readonly insertToken: (token: Omit<TokenRecord, 'consumedAt' | 'createdAt'>) => Effect.Effect<TokenRecord>;
+    /** Atomically redeem a token by its hash + purpose: returns the row
+     *  only when it exists, matches the purpose, is unexpired, and was not
+     *  already consumed — and marks it consumed in the same step. Returns
+     *  null otherwise (single-use guard). */
+    readonly consumeToken: (tokenHash: string, purpose: TokenPurpose) => Effect.Effect<TokenRecord | null>;
+    /** Replace the user's recovery codes with a fresh (already hashed) set.
+     *  Called at enrolment / regeneration — wipes any prior codes so the
+     *  displayed set is the only valid one. */
+    readonly replaceRecoveryCodes: (userId: string, codeHashes: ReadonlyArray<string>) => Effect.Effect<void>;
+    /** Atomically redeem one recovery code by its hash: returns true only
+     *  when an unconsumed row for `userId` matched — and marks it consumed
+     *  in the same step (single-use). false otherwise. */
+    readonly consumeRecoveryCode: (userId: string, codeHash: string) => Effect.Effect<boolean>;
+    /** Count the user's remaining (unconsumed) recovery codes — surfaced so
+     *  the UI can warn when the user is running low. */
+    readonly countRecoveryCodes: (userId: string) => Effect.Effect<number>;
+    readonly listPasskeys: (userId: string) => Effect.Effect<ReadonlyArray<PasskeyRecord>>;
+    readonly findPasskey: (credentialId: string) => Effect.Effect<PasskeyRecord | null>;
+    readonly insertPasskey: (passkey: Omit<PasskeyRecord, 'createdAt' | 'lastUsedAt'>) => Effect.Effect<PasskeyRecord>;
+    /** Atomically bump the stored signature counter, guarding against a
+     *  cloned authenticator (WebAuthn §6.1.1): the update only applies when
+     *  `newCounter` strictly exceeds the stored counter. Returns whether a
+     *  row was advanced. `false` with an unchanged stored counter is the
+     *  clone/replay signal the assertion handler rejects on — the check and
+     *  the write are ONE atomic statement at the store, so two replicas
+     *  racing the same counter can't both succeed. */
+    readonly advancePasskeyCounter: (credentialId: string, newCounter: number) => Effect.Effect<boolean>;
+}
+
+export { }

package/dist/plugin.js

@@ -0,0 +1,4 @@
+import "./session.js";
+import { n as e, t } from "./plugin-CRt-kdEA.js";
+import "./csrf.js";
+export { t as authRoutesPlugin, e as getAuthSessionStrategy };

package/dist/schema.d.ts

@@ -0,0 +1,72 @@
+import { TableLike } from '@voltro/database';
+
+/** Tables the plugin contributes, as an array. */
+export declare const authTables: readonly [TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike];
+
+/**
+ * Auth-token table. Single-use, hashed, expiring tokens for the
+ * magic-link sign-in + password-reset flows. We store only the SHA-256
+ * of the token (never the plaintext) so a DB leak can't be replayed.
+ * `purpose` discriminates the flow; `consumedAt` is set the first time
+ * a token is redeemed (single-use guard).
+ */
+export declare const authTokensTable: TableLike;
+
+/**
+ * Memberships table. A user belongs to MANY tenants; each row is one
+ * membership with a `role`. The active tenant lives on the Subject, but
+ * the set of tenants a user MAY switch into is enumerated here.
+ *
+ * `[userId, tenantId]` is a composite UNIQUE — the DB enforces the
+ * one-membership-per-(user, tenant) invariant that `addMembership`
+ * upserts toward, and the unique constraint doubles as the BTREE index
+ * backing the membership lookup + the dedup probe (so no separate
+ * `.index([...])` on the same columns is needed).
+ */
+export declare const membershipsTable: TableLike;
+
+/**
+ * Passkey ceremony challenges — the DataStore-backed `ChallengeStore`
+ * (`dataStoreChallengeStore`) writes here so a multi-replica deployment's
+ * register/assert ceremonies survive when `options` and `verify` land on
+ * different replicas (the in-memory store is single-node only). Rows are
+ * single-use + short-lived: `take` deletes on read, and `expiresAt` bounds
+ * a challenge abandoned before verify. `key` is `<userId>:<ceremony>`.
+ */
+export declare const passkeyChallengesTable: TableLike;
+
+/**
+ * Passkey (WebAuthn) credentials. One row per registered authenticator.
+ * `publicKey` is the COSE public key (base64url). `counter` is the
+ * authenticator's signature counter — the assertion handler rejects any
+ * assertion whose counter does not strictly exceed the stored value
+ * (cloned-authenticator detection).
+ */
+export declare const passkeysTable: TableLike;
+
+/**
+ * MFA recovery (backup) codes. One row per code, stored HASHED (SHA-256,
+ * same as auth tokens — never the plaintext). Minted at enrolment, shown
+ * once, single-use: `consumedAt` is stamped the first time a code is
+ * redeemed at sign-in as the authenticator-loss fallback.
+ */
+export declare const recoveryCodesTable: TableLike;
+
+/**
+ * Sessions table. Active sessions enumerated server-side so apps can
+ * implement "sign out other devices" + server-side revocation.
+ * `handleSignIn` / `handleSignOut` do NOT write here (cookies are
+ * self-describing HMAC-signed); apps that need device management
+ * wire that up themselves.
+ */
+export declare const sessionsTable: TableLike;
+
+/**
+ * Users table. `tenantId` is a plain text column (not a reference)
+ * so the table can be added to apps that haven't yet declared their
+ * own `tenants` table. Apps with a tenants store can layer a
+ * referential constraint on top via the DB schema or DSL extensions.
+ */
+export declare const usersTable: TableLike;
+
+export { }

package/dist/schema.js

@@ -0,0 +1,66 @@
+import { id as e, integer as t, table as n, text as r, timestamp as i } from "@voltro/database";
+//#region src/schema/index.ts
+var a = n("users", {
+	id: e(),
+	email: r().unique(),
+	passwordHash: r(),
+	tenantId: r(),
+	mfaSecret: r().nullable(),
+	mfaEnrolledAt: i().nullable(),
+	createdAt: i().default("now"),
+	updatedAt: i().default("now").onUpdate("now")
+}).index(["tenantId"]), o = n("sessions", {
+	id: e(),
+	userId: r(),
+	tenantId: r(),
+	expiresAt: i(),
+	ipAddress: r().nullable(),
+	userAgent: r().nullable(),
+	createdAt: i().default("now"),
+	lastSeenAt: i().default("now").onUpdate("now")
+}).index(["userId"]).index(["tenantId"]), s = n("memberships", {
+	id: e(),
+	userId: r(),
+	tenantId: r(),
+	role: r(),
+	joinedAt: i().default("now")
+}).unique("byUserTenant", ["userId", "tenantId"]).index(["tenantId"]), c = n("authTokens", {
+	id: e(),
+	tokenHash: r().unique(),
+	userId: r(),
+	purpose: r(),
+	expiresAt: i(),
+	consumedAt: i().nullable(),
+	createdAt: i().default("now")
+}).index(["userId"]).index(["purpose"]), l = n("passkeys", {
+	id: e(),
+	credentialId: r().unique(),
+	userId: r(),
+	publicKey: r(),
+	counter: t().default(0),
+	transports: r().nullable(),
+	createdAt: i().default("now"),
+	lastUsedAt: i().nullable()
+}).index(["userId"]), u = n("recoveryCodes", {
+	id: e(),
+	userId: r(),
+	codeHash: r(),
+	consumedAt: i().nullable(),
+	createdAt: i().default("now")
+}).index(["userId"]), d = n("passkeyChallenges", {
+	id: e(),
+	key: r().unique(),
+	challenge: r(),
+	expiresAt: i(),
+	createdAt: i().default("now")
+}), f = [
+	a,
+	o,
+	s,
+	c,
+	l,
+	u,
+	d
+];
+//#endregion
+export { f as authTables, c as authTokensTable, s as membershipsTable, d as passkeyChallengesTable, l as passkeysTable, u as recoveryCodesTable, o as sessionsTable, a as usersTable };

package/dist/session.d.ts

@@ -0,0 +1,86 @@
+import { KeyedSecret } from '@voltro/protocol/session';
+import { SessionSecrets } from '@voltro/protocol/session';
+import { Subject } from '@voltro/protocol';
+import { VerifyOptions } from '@voltro/protocol/session';
+import { VerifyResult } from '@voltro/protocol/session';
+
+/**
+ * Build a `Set-Cookie` value that clears the session cookie. Send
+ * this on logout.
+ */
+export declare const clearSessionCookie: (options?: IssueSessionOptions) => string;
+
+export declare interface IssuedSession {
+    /** The opaque cookie value — `<payload>.<sig>`. */
+    readonly value: string;
+    /** Ready-to-Set-Cookie header string with sane defaults. */
+    readonly setCookie: string;
+}
+
+/**
+ * Mint a signed session AND build the corresponding `Set-Cookie`
+ * header in one call. Apps just attach the header to their
+ * response. Pass a `SessionSecrets` set to sign with the current
+ * rotation key (its `kid` is stamped into the payload).
+ */
+export declare const issueSession: (subject: Subject, secret: SessionSecretInput, options?: IssueSessionOptions) => IssuedSession;
+
+export declare interface IssueSessionOptions {
+    readonly ttlSeconds?: number;
+    readonly domain?: string;
+    readonly secure?: boolean;
+}
+
+export { KeyedSecret }
+
+/**
+ * Read + verify the session cookie from a Cookie header string.
+ * Returns the decoded Subject or null when the cookie is missing,
+ * malformed, tampered, or expired. Never throws — callers branch
+ * on the boolean.
+ *
+ * Verification is keyed: the given secret is widened via
+ * `sessionSecretsOf`, so a cookie signed with the previous rotation
+ * key keeps verifying while `VOLTRO_SESSION_SECRET_PREVIOUS` is set.
+ */
+export declare const readSession: (cookieHeader: string | undefined, secret: SessionSecretInput) => Subject | null;
+
+/**
+ * Keyed read: the full `VerifyResult` — subject + the `kid` that
+ * verified + the sliding-window `renew` flag + `exp`/`iat`. The auth
+ * routes plugin re-issues the cookie when `renew` is set or when the
+ * value verified under the previous key.
+ */
+export declare const readSessionKeyed: (cookieHeader: string | undefined, secret: SessionSecretInput, options?: VerifyOptions) => VerifyResult | null;
+
+export declare const resolveSessionSecret: () => string;
+
+export declare const resolveSessionSecrets: () => SessionSecrets;
+
+export declare const SESSION_COOKIE_NAME: "voltro:session";
+
+/** Every session helper takes either a bare secret string (single-key)
+ *  or the keyed `{ current, previous? }` rotation set. */
+export declare type SessionSecretInput = string | SessionSecrets;
+
+export { SessionSecrets }
+
+/**
+ * Normalise a secret input into the keyed set VERIFICATION runs against.
+ *
+ *   - A `SessionSecrets` set passes through unchanged.
+ *   - A bare string becomes `current` and is widened with the env-driven
+ *     `previous` key (`VOLTRO_SESSION_SECRET_PREVIOUS` +
+ *     `VOLTRO_SESSION_KID_PREVIOUS`) so env-var rotation works without
+ *     the app switching its config to the keyed shape. When the string
+ *     IS the env secret (`VOLTRO_SESSION_SECRET`), it inherits the env
+ *     `kid`; otherwise the default kid applies. The comparison is
+ *     constant-time — secrets never go through `===`.
+ */
+export declare const sessionSecretsOf: (secret: SessionSecretInput) => SessionSecrets;
+
+export { VerifyResult }
+
+export declare const VOLTRO_DEV_SESSION_SECRET: "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD";
+
+export { }

package/dist/session.js

@@ -0,0 +1,38 @@
+import { DEFAULT_SESSION_KID as e, VOLTRO_DEV_SESSION_SECRET as t, buildSetCookie as n, readCookie as r, resolveSessionSecret as i, resolveSessionSecrets as a, signSession as o, timingSafeStringEqual as s, verifySessionKeyed as c } from "@voltro/protocol/session";
+//#region src/session.ts
+var l = "voltro:session", u = 3600 * 24 * 7, d = t, f = i, p = a, m = (e) => typeof e == "string" ? e : e.current, h = (t) => {
+	if (typeof t != "string") return t;
+	let n = a(), r = {
+		kid: s(n.current.secret, t) ? n.current.kid : e,
+		secret: t
+	};
+	return n.previous ? {
+		current: r,
+		previous: n.previous
+	} : { current: r };
+}, g = (e, t, r = {}) => {
+	let i = r.ttlSeconds ?? u, a = o(e, m(t), { ttlSeconds: i });
+	return {
+		value: a,
+		setCookie: n(l, a, {
+			maxAgeSeconds: i,
+			httpOnly: !0,
+			sameSite: "lax",
+			secure: r.secure ?? !0,
+			...r.domain ? { domain: r.domain } : {},
+			path: "/"
+		})
+	};
+}, _ = (e, t) => v(e, t)?.subject ?? null, v = (e, t, n = {}) => {
+	let i = r(e, l);
+	return i ? c(i, h(t), n) : null;
+}, y = (e = {}) => n(l, "", {
+	maxAgeSeconds: 0,
+	httpOnly: !0,
+	sameSite: "lax",
+	secure: e.secure ?? !0,
+	...e.domain ? { domain: e.domain } : {},
+	path: "/"
+});
+//#endregion
+export { l as SESSION_COOKIE_NAME, d as VOLTRO_DEV_SESSION_SECRET, y as clearSessionCookie, g as issueSession, _ as readSession, v as readSessionKeyed, f as resolveSessionSecret, p as resolveSessionSecrets, h as sessionSecretsOf };