better-dsh 0.2.4-c → 0.2.5-a

package/lib/web-password.d.ts

@@ -0,0 +1,156 @@
+import { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { CredentialRecord } from "@deepseek-ai/dsh-credentials";
+import { IncomingMessage } from "node:http";
+
+//#region src/web-password.d.ts
+
+/** Native cookie envelope version. */
+declare const COOKIE_PAYLOAD_VERSION = 1;
+declare const PASSWORD_RECORD_VERSION = 1;
+/** What the native verifier expects inside a browser cookie. */
+interface BrowserCookiePayload {
+  readonly version: typeof COOKIE_PAYLOAD_VERSION;
+  readonly authority: string;
+  readonly issuedAt: number;
+  readonly expiresAt: number;
+}
+/** This row's stored password record payload. */
+interface StoredPasswordPayload {
+  readonly version: typeof PASSWORD_RECORD_VERSION;
+  readonly algorithm: 'scrypt';
+  /** base64url salt. */
+  readonly salt: string;
+  /** base64url derived key. */
+  readonly hash: string;
+  readonly N: number;
+  readonly r: number;
+  readonly p: number;
+  readonly keylen: number;
+}
+/** base64url-encode bytes without padding (the native cookie's alphabet). */
+declare function encodeBase64Url(value: Uint8Array): string;
+/**
+ * Decode a canonical base64url string; non-canonical input is rejected rather
+ * than silently normalized, which is what makes a tampered payload fail closed.
+ * @param value - the candidate string.
+ * @returns the bytes, or `undefined` when it is not canonical base64url.
+ */
+declare function decodeBase64Url(value: string): Buffer | undefined;
+/**
+ * The native cookie name for one request authority.
+ * @param authority - canonical `host` or `host:port`.
+ * @returns the cookie name.
+ */
+declare function cookieName(authority: string): string;
+/**
+ * Mint a native-format browser-session cookie value.
+ * @param payload - the session claims.
+ * @param secret - the native signing key.
+ * @returns `v1.<base64url payload>.<base64url HMAC>`.
+ */
+declare function encodeSessionCookie(payload: BrowserCookiePayload, secret: Buffer): string;
+/**
+ * Verify and decode a native-format browser-session cookie value.
+ * @param value - the cookie value.
+ * @param secret - the native signing key.
+ * @returns the claims, or `undefined` when the envelope, signature, or shape fails.
+ */
+declare function decodeSessionCookie(value: string, secret: Buffer): BrowserCookiePayload | undefined;
+/**
+ * Canonical request authority: the native cookie name and its signed audience.
+ * @param headers - the incoming request headers.
+ * @returns `host` or `host:port`, lowercased, or `undefined` without a usable Host.
+ */
+declare function requestAuthority(headers: IncomingMessage['headers']): string | undefined;
+/**
+ * Serialize the fixed browser-session attributes; generated names and values
+ * are cookie-safe base64url. Mirrors the native attribute set exactly.
+ */
+declare function sessionCookieHeader(name: string, value: string, expiresAt: number, maxAgeSeconds: number): string;
+/**
+ * Verify the native browser cookie on one request, with the native checks:
+ * authority binding, issued/expiry window, and a lifetime no longer than ours.
+ * @param headers - incoming request headers carrying Host and Cookie.
+ * @param secret - the native signing key.
+ * @param maxAgeMilliseconds - the longest lifetime this deployment accepts.
+ * @returns true only for a live cookie signed by the native key for this authority.
+ */
+declare function sessionAuthenticated(headers: IncomingMessage['headers'], secret: Buffer, maxAgeMilliseconds: number): boolean;
+/**
+ * Derive the scrypt key for one password.
+ * @param password - the submitted password.
+ * @param payload - salt and work factors.
+ * @returns the derived key.
+ */
+declare function derivePasswordKey(password: string, payload: Pick<StoredPasswordPayload, 'salt' | 'N' | 'r' | 'p' | 'keylen'>): Promise<Buffer>;
+/**
+ * Constant-time password check against a stored payload.
+ * @param password - the submitted password.
+ * @param payload - the stored record.
+ * @returns true only on an exact match.
+ */
+declare function verifyPassword(password: string, payload: StoredPasswordPayload): Promise<boolean>;
+/**
+ * Build a fresh stored payload for one password (random salt).
+ * @param password - the password to store.
+ * @returns the payload to write into the credential record.
+ */
+declare function seedPasswordPayload(password: string): Promise<StoredPasswordPayload>;
+/**
+ * Interpret one password record; a present-but-unsupported record is loud
+ * (fail closed) rather than silently treated as absent.
+ * @param record - the stored record, when any.
+ * @returns the payload, or `undefined` when no record is stored.
+ */
+declare function parsePasswordPayload(record: CredentialRecord | undefined): StoredPasswordPayload | undefined;
+/**
+ * The sign-in page. Server-rendered, self-contained, no external resource: it
+ * is the only thing an unauthenticated request ever receives.
+ * @param notice - optional failure text.
+ * @returns the complete HTML document.
+ */
+declare function loginPage(notice?: string): string;
+/**
+ * Insert the relative base the served dist needs, exactly as the native
+ * fallback owner does, so every asset reference resolves under the mount.
+ * @param html - the rendered index markup.
+ * @returns the markup with `<base href="./">` after the head open tag.
+ */
+declare function withBaseHref(html: string): string;
+/** Row config: the only knob is how long a minted session lives. */
+interface WebPasswordConfig {
+  /** Absolute browser-session lifetime in days. Default: 30 (the native default). */
+  cookieMaxAgeDays?: number;
+}
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  cookieMaxAgeDays: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  cookieMaxAgeDays: z<number, number, "defined">;
+}>>, "plain">;
+/** Cordis plugin name; also the scope of this row's credential record. */
+declare const name = "dashr-web-password";
+/**
+ * No static injects: the gate is composed around `webServer`, `connection`
+ * (which owns the session secret), and `credentials`, so a composition without
+ * a browser surface loads this row dormant.
+ */
+declare const inject: string[];
+/**
+ * Claim exact `/` and put the password in front of it.
+ * @param ctx - host plugin context.
+ * @param config - the row config.
+ */
+declare function apply(ctx: Context, config?: WebPasswordConfig): void;
+declare const _default: {
+  name: string;
+  inject: string[];
+  Config: z<Schemastery.ObjectS<NoInfer<{
+    cookieMaxAgeDays: z<number, number, "defined">;
+  }>>, Schemastery.ObjectT<NoInfer<{
+    cookieMaxAgeDays: z<number, number, "defined">;
+  }>>, "plain">;
+  apply: typeof apply;
+};
+//#endregion
+export { BrowserCookiePayload, Config, StoredPasswordPayload, WebPasswordConfig, apply, cookieName, decodeBase64Url, decodeSessionCookie, _default as default, derivePasswordKey, encodeBase64Url, encodeSessionCookie, inject, loginPage, name, parsePasswordPayload, requestAuthority, seedPasswordPayload, sessionAuthenticated, sessionCookieHeader, verifyPassword, withBaseHref };