@shipstatic/types 0.9.8 → 0.9.10

package/README.md

@@ -68,7 +68,7 @@ try { response = await fetch(url); }
 catch (cause) { throw ShipError.fromFetchError(cause, 'Get account'); }
 ```
 
-`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 429 → `RateLimit`, else → `Api`). Body's `message` and `details` are preserved best-effort.
+`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 403 → `Forbidden`, 429 → `RateLimit`, else → `Api`). Client-only types (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the trusted set. Body's `message` and `details` are preserved best-effort.
 
 `fromFetchError` routes by the thrown cause: an existing `ShipError` is returned unchanged, `AbortError` becomes `Cancelled`, a fetch `TypeError` becomes `Network`, anything else becomes `Api` (with no HTTP status — the request never reached the server).
 
@@ -159,6 +159,15 @@ import {
 } from '@shipstatic/types';
 ```
 
+### Password Utilities
+
+```typescript
+import {
+  PASSWORD_CONSTRAINTS,   // { MIN_LENGTH: 6, MAX_LENGTH: 128 }
+  validatePassword,       // (value: unknown) => string | undefined
+} from '@shipstatic/types';
+```
+
 ### Constants
 
 ```typescript

package/dist/index.d.ts

@@ -692,7 +692,8 @@ export interface DeploymentUploadOptions {
      * Optional password that protects this deployment.
      *
      * Length: {@link PASSWORD_CONSTRAINTS.MIN_LENGTH} to
-     * {@link PASSWORD_CONSTRAINTS.MAX_LENGTH} characters; whitespace is
+     * {@link PASSWORD_CONSTRAINTS.MAX_LENGTH} characters. Leading and trailing
+     * whitespace is trimmed before validation; internal whitespace is
      * significant. Visitors are prompted to enter the password before they can
      * view the deployment — including on any custom domains pointing at it.
      * To remove protection, redeploy without a password.
@@ -1012,3 +1013,25 @@ export declare const PASSWORD_CONSTRAINTS: {
     /** Maximum password length in characters */
     readonly MAX_LENGTH: 128;
 };
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`. Present → trim
+ * leading/trailing whitespace, then validate against `PASSWORD_CONSTRAINTS`
+ * length bounds (internal whitespace is significant and counts toward
+ * length). Throws `ShipError.validation` on breach; returns the trimmed
+ * value.
+ *
+ * The trim is canonical: at upload, the API hashes the trimmed value; at
+ * unlock, the router trims submissions before hashing. Submission and storage
+ * agree byte-for-byte. Length validation runs on the trimmed value because
+ * that's the user's actual intent — and it disarms a class of invisible
+ * foot-guns (trailing newlines from copy/paste, mobile auto-spacing,
+ * password-manager artifacts).
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+export declare function validatePassword(value: unknown): string | undefined;

package/dist/index.js

@@ -661,3 +661,37 @@ export const PASSWORD_CONSTRAINTS = {
     /** Maximum password length in characters */
     MAX_LENGTH: 128,
 };
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`. Present → trim
+ * leading/trailing whitespace, then validate against `PASSWORD_CONSTRAINTS`
+ * length bounds (internal whitespace is significant and counts toward
+ * length). Throws `ShipError.validation` on breach; returns the trimmed
+ * value.
+ *
+ * The trim is canonical: at upload, the API hashes the trimmed value; at
+ * unlock, the router trims submissions before hashing. Submission and storage
+ * agree byte-for-byte. Length validation runs on the trimmed value because
+ * that's the user's actual intent — and it disarms a class of invisible
+ * foot-guns (trailing newlines from copy/paste, mobile auto-spacing,
+ * password-manager artifacts).
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+export function validatePassword(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw ShipError.validation('Password must be a string');
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < PASSWORD_CONSTRAINTS.MIN_LENGTH ||
+        trimmed.length > PASSWORD_CONSTRAINTS.MAX_LENGTH) {
+        throw ShipError.validation(`Password must be between ${PASSWORD_CONSTRAINTS.MIN_LENGTH} and ${PASSWORD_CONSTRAINTS.MAX_LENGTH} characters`);
+    }
+    return trimmed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -1065,7 +1065,8 @@ export interface DeploymentUploadOptions {
    * Optional password that protects this deployment.
    *
    * Length: {@link PASSWORD_CONSTRAINTS.MIN_LENGTH} to
-   * {@link PASSWORD_CONSTRAINTS.MAX_LENGTH} characters; whitespace is
+   * {@link PASSWORD_CONSTRAINTS.MAX_LENGTH} characters. Leading and trailing
+   * whitespace is trimmed before validation; internal whitespace is
    * significant. Visitors are prompted to enter the password before they can
    * view the deployment — including on any custom domains pointing at it.
    * To remove protection, redeploy without a password.
@@ -1524,4 +1525,42 @@ export const PASSWORD_CONSTRAINTS = {
   MIN_LENGTH: 6,
   /** Maximum password length in characters */
   MAX_LENGTH: 128,
-} as const;
+} as const;
+
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`. Present → trim
+ * leading/trailing whitespace, then validate against `PASSWORD_CONSTRAINTS`
+ * length bounds (internal whitespace is significant and counts toward
+ * length). Throws `ShipError.validation` on breach; returns the trimmed
+ * value.
+ *
+ * The trim is canonical: at upload, the API hashes the trimmed value; at
+ * unlock, the router trims submissions before hashing. Submission and storage
+ * agree byte-for-byte. Length validation runs on the trimmed value because
+ * that's the user's actual intent — and it disarms a class of invisible
+ * foot-guns (trailing newlines from copy/paste, mobile auto-spacing,
+ * password-manager artifacts).
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+export function validatePassword(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw ShipError.validation('Password must be a string');
+  }
+  const trimmed = value.trim();
+  if (
+    trimmed.length < PASSWORD_CONSTRAINTS.MIN_LENGTH ||
+    trimmed.length > PASSWORD_CONSTRAINTS.MAX_LENGTH
+  ) {
+    throw ShipError.validation(
+      `Password must be between ${PASSWORD_CONSTRAINTS.MIN_LENGTH} and ${PASSWORD_CONSTRAINTS.MAX_LENGTH} characters`,
+    );
+  }
+  return trimmed;
+}