@spfn/auth 0.2.1 → 0.3.0-beta.1

package/dist/session-DTHahDQ9.d.ts

@@ -0,0 +1,53 @@
+import { K as KeyAlgorithmType } from './types-DYyhze28.js';
+
+/**
+ * @spfn/auth - Client Session Management
+ *
+ * Uses Jose JWE (JSON Web Encryption) to securely store session data in cookies
+ * More efficient than Iron Session with better Edge Runtime support
+ */
+
+interface SessionData {
+    userId: string;
+    privateKey: string;
+    keyId: string;
+    algorithm: KeyAlgorithmType;
+}
+/**
+ * Seal session data into encrypted JWT (JWE)
+ *
+ * @param data - Session data to encrypt
+ * @param ttl - Time to live in seconds (default: 7 days)
+ * @returns Encrypted JWT string
+ */
+declare function sealSession(data: SessionData, ttl?: number): Promise<string>;
+/**
+ * Unseal encrypted JWT (JWE) to session data
+ *
+ * @param jwt - Encrypted JWT string
+ * @returns Session data
+ * @throws Error if session is invalid or expired
+ */
+declare function unsealSession(jwt: string): Promise<SessionData>;
+/**
+ * Get session metadata without decrypting
+ *
+ * @param jwt - Encrypted JWT string
+ * @returns Session metadata or null if invalid
+ */
+declare function getSessionInfo(jwt: string): Promise<{
+    issuedAt: Date;
+    expiresAt: Date;
+    issuer: string;
+    audience: string;
+} | null>;
+/**
+ * Check if session is about to expire (within threshold)
+ *
+ * @param jwt - Encrypted JWT string
+ * @param thresholdHours - Hours before expiry to trigger refresh (default: 24)
+ * @returns True if session should be refreshed
+ */
+declare function shouldRefreshSession(jwt: string, thresholdHours?: number): Promise<boolean>;
+
+export { type SessionData as S, shouldRefreshSession as a, getSessionInfo as g, sealSession as s, unsealSession as u };

package/dist/types-DYyhze28.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @spfn/auth - Shared Types
+ *
+ * Common types and constants used across the auth package
+ */
+/**
+ * Supported JWT signature algorithms
+ *
+ * - ES256: ECDSA with P-256 and SHA-256 (recommended, smaller keys)
+ * - RS256: RSA with SHA-256 (fallback, larger keys)
+ */
+declare const KEY_ALGORITHM: readonly ["ES256", "RS256"];
+/**
+ * Key algorithm type derived from the const array
+ */
+type KeyAlgorithmType = typeof KEY_ALGORITHM[number];
+/**
+ * Where a registered key lives, as the client declares it.
+ *
+ * Only for telling one entry apart from another in the key list — nothing is
+ * authorized or refused by it, so a client that lies gains nothing. Stored via
+ * `enumText`, so adding a value here needs no migration.
+ */
+declare const KEY_PLATFORM: readonly ["ios", "android", "web", "desktop"];
+/**
+ * Key platform type derived from the const array
+ */
+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;
+/**
+ * Invitation status enum values
+ * Single source of truth for all invitation statuses
+ */
+declare const INVITATION_STATUSES: readonly ["pending", "accepted", "expired", "cancelled"];
+/**
+ * Invitation status type derived from the const array
+ */
+type InvitationStatus = typeof INVITATION_STATUSES[number];
+/**
+ * User status enum values
+ * Single source of truth for all user statuses
+ *
+ * - active: Normal operation (default)
+ * - inactive: Deactivated (user request, dormant)
+ * - suspended: Locked (security incident, ToS violation)
+ * - pending_deletion: Deletion requested, within the grace period (recoverable)
+ * - deleted: Grace period elapsed and the account was purged (anonymize mode only —
+ *   hard-delete removes the row instead, so this status never appears for it)
+ */
+declare const USER_STATUSES: readonly ["active", "inactive", "suspended", "pending_deletion", "deleted"];
+/**
+ * User status type derived from the const array
+ */
+type UserStatus = typeof USER_STATUSES[number];
+/**
+ * Social provider enum values
+ * Single source of truth for supported OAuth providers
+ */
+declare const SOCIAL_PROVIDERS: readonly ["google", "apple", "github", "kakao", "naver", "superself"];
+/**
+ * Social provider type derived from the const array
+ */
+type SocialProvider = typeof SOCIAL_PROVIDERS[number];
+/**
+ * Account deletion request status enum values
+ * Single source of truth for `account_deletion_requests.status`
+ *
+ * - pending: Awaiting the grace period (or immediate purge)
+ * - cancelled: User (or admin) recovered the account before purge
+ * - completed: The purge ran (row is kept as an audit record, never deleted)
+ */
+declare const ACCOUNT_DELETION_REQUEST_STATUSES: readonly ["pending", "cancelled", "completed"];
+/**
+ * Account deletion request status type derived from the const array
+ */
+type AccountDeletionRequestStatus = typeof ACCOUNT_DELETION_REQUEST_STATUSES[number];
+/**
+ * Who initiated an account deletion request
+ */
+declare const ACCOUNT_DELETION_REQUESTED_BY: readonly ["self", "admin"];
+/**
+ * Account deletion requester type derived from the const array
+ */
+type AccountDeletionRequestedBy = typeof ACCOUNT_DELETION_REQUESTED_BY[number];
+/**
+ * Purge strategy enum values
+ *
+ * - anonymize: Scrub PII, keep the row (status becomes 'deleted') — default
+ * - hard-delete: Physically remove the `users` row (cascades to child rows)
+ */
+declare const PURGE_STRATEGIES: readonly ["anonymize", "hard-delete"];
+/**
+ * Purge strategy type derived from the const array
+ */
+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 };

package/dist/wire-version-CtzMKvBB.d.ts

@@ -0,0 +1,134 @@
+/** The six wire codes. The SDKs classify by code, never HTTP status. */
+type ClientProofErrorCode = 'PROOF_INVALID' | 'PROOF_REPLAYED' | 'PROOF_EXPIRED' | 'SESSION_REVOKED' | 'PROFILE_REJECTED' | 'CONTRACT_UNSUPPORTED';
+/** 128 random bits as lowercase base16 — request ids and control tokens. */
+declare function newHexId(): string;
+declare class ClientProofRefusal {
+    readonly code: ClientProofErrorCode;
+    readonly message: string;
+    constructor(code: ClientProofErrorCode, message: string);
+    get httpStatus(): number;
+    /** The canonical bytes of `{"error":{"code":…,"message":…,"requestId":…}}`. */
+    envelopeBytes(requestId: string): Uint8Array;
+    /** Nothing request-derived reaches a log through this. */
+    toString(): string;
+    static unroutable(): ClientProofRefusal;
+    static malformedHeaders(): ClientProofRefusal;
+    static missingContentType(): ClientProofRefusal;
+    static bodyTooLarge(): ClientProofRefusal;
+    /**
+     * The body parsed but its bytes are not the canonical form of what it
+     * parsed to. Not PROOF_INVALID even though it is discovered next to the
+     * proof: the proof over these bytes verifies perfectly well, and an
+     * auth-family answer would tell the client to re-handshake and send the
+     * same non-canonical bytes again.
+     */
+    static bodyNotCanonical(): ClientProofRefusal;
+    static bodyNotTheDeclaredType(): ClientProofRefusal;
+    static sessionHeaderMisplaced(): ClientProofRefusal;
+    static unprocessable(): ClientProofRefusal;
+    /**
+     * A client that ships separately from the server said nothing about which
+     * contract it was built against. Without it the server cannot tell whether
+     * the two ends agree, and answering as though they do is what produces the
+     * undecodable body this check exists to replace.
+     */
+    static contractVersionMissing(): ClientProofRefusal;
+    static contractVersionUnsupported(): ClientProofRefusal;
+    static profileRejected(): ClientProofRefusal;
+    /**
+     * A request that names a profile and presents Bearer credentials as well.
+     * The profile named is a real one, so this is not a shape the two ends
+     * disagree about: the request asked to be authenticated two ways at once
+     * and the profile it named is the one refused.
+     */
+    static credentialsMixed(): ClientProofRefusal;
+    static sessionRevoked(): ClientProofRefusal;
+    static proofExpired(): ClientProofRefusal;
+    static proofReplayed(): ClientProofRefusal;
+    static proofInvalid(): ClientProofRefusal;
+}
+
+/**
+ * The header names each end announces itself under.
+ *
+ * Separated from the logic that reads them so the contract bundle can name them
+ * without importing the version comparison, which reads the bundle back. These
+ * are declarations and depend on nothing.
+ *
+ * @module server/client-proof/wire-headers
+ */
+/** What a client says about itself, one header each. */
+declare const CLIENT_IDENTITY_HEADERS: {
+    readonly kind: "x-spfn-client-kind";
+    readonly version: "x-spfn-client-version";
+    readonly contractVersion: "x-spfn-client-contract-version";
+};
+/**
+ * What the server says about itself, on every response.
+ *
+ * Distinct names from the request headers on purpose: a proxy that echoes a
+ * request header into the response would otherwise make the client's own
+ * version look like the server's.
+ */
+declare const SERVER_CONTRACT_HEADERS: {
+    readonly version: "x-spfn-server-contract-version";
+    readonly supportedRange: "x-spfn-supported-contract-range";
+};
+/**
+ * The client kinds the server distinguishes.
+ *
+ * `web` is separated from the two app kinds because it carries no contract
+ * version: a browser bundle is deployed with the server that serves it, so
+ * there is no second version to reconcile.
+ */
+declare const CLIENT_KINDS: readonly ["web", "ios", "android"];
+type ClientKind = typeof CLIENT_KINDS[number];
+/** A kind that ships independently of the server, so its contract version matters. */
+declare function isAppKind(kind: ClientKind): boolean;
+
+/** What one request announced about the client that sent it. */
+interface ClientIdentity {
+    kind: ClientKind;
+    /** The client's own release — a store version, or a bundle build. */
+    version: string | null;
+    /** The contract version the client was generated from. Never set for `web`. */
+    contractVersion: string | null;
+}
+/**
+ * Reads the identity headers, or null when the kind is absent or unrecognised.
+ *
+ * Null is not by itself a refusal — a request from something that predates
+ * these headers reaches here too. `judgeClientIdentity` decides.
+ */
+declare function readClientIdentity(headers: Headers): ClientIdentity | null;
+/**
+ * Whether the server serves what the client was generated against.
+ *
+ * Under 0.x the minor carries breaking changes, so a supported client agrees on
+ * major and minor. From 1.0.0 the major alone decides. This is the rule
+ * `CONTRACT_SUPPORTED_RANGE` spells out; keeping it as a comparison rather than
+ * parsing that string leaves one place to change when the line reaches 1.0.0.
+ */
+declare function isContractVersionSupported(clientVersion: string): boolean;
+/**
+ * The refusal a request's announced identity earns, or null to let it through.
+ *
+ * An app kind must state a contract version this server serves. A version it
+ * does not serve, and the absence of one, are the same answer: the two ends do
+ * not agree on what the contract is, which is what CONTRACT_UNSUPPORTED means.
+ * The response carries the server's version and range, so the client can say
+ * which way the gap runs.
+ *
+ * `web` is exempt from the contract check by construction, not by leniency.
+ *
+ * A request with no recognised kind passes. The check is on what a client says
+ * about itself, and a caller that says nothing — a curl, a health probe, a
+ * server-to-server call — is not a deployed client this rule is about.
+ */
+declare function judgeClientIdentity(identity: ClientIdentity | null): ClientProofRefusal | null;
+/** Writes the server's own announcement onto a response's headers. */
+declare function applyServerContractHeaders(headers: Headers): void;
+/** The same announcement as a plain object, for a response built from one. */
+declare function serverContractHeaders(): Record<string, string>;
+
+export { ClientProofRefusal as C, SERVER_CONTRACT_HEADERS as S, CLIENT_IDENTITY_HEADERS as a, CLIENT_KINDS as b, type ClientIdentity as c, type ClientKind as d, type ClientProofErrorCode as e, applyServerContractHeaders as f, isContractVersionSupported as g, isAppKind as i, judgeClientIdentity as j, newHexId as n, readClientIdentity as r, serverContractHeaders as s };