@shipstatic/types 2.1.0 → 2.2.1-beta.0

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export declare const DeploymentStatus: {
     readonly FAILED: "failed";
     readonly DELETING: "deleting";
 };
-export type DeploymentStatusType = typeof DeploymentStatus[keyof typeof DeploymentStatus];
+export type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -74,7 +74,7 @@ export declare const DomainStatus: {
     readonly SUCCESS: "success";
     readonly PAUSED: "paused";
 };
-export type DomainStatusType = typeof DomainStatus[keyof typeof DomainStatus];
+export type DomainStatusType = (typeof DomainStatus)[keyof typeof DomainStatus];
 /**
  * Core domain object - used in both API responses and SDK
  */
@@ -178,30 +178,10 @@ export interface DomainValidateResponse {
     /** Error message, null when valid */
     error: string | null;
 }
-/**
- * Deployment token for automated deployments
- */
-export interface Token {
-    /** 7-char management identifier */
-    readonly token: string;
-    /** The account this token belongs to */
-    readonly account: string;
-    /** SHA256 hash of the raw credential (auth lookups only, never exposed to users) */
-    readonly hash: string;
-    /** IP-lock. Non-null = single-use (claimable only from this IP, once); null = multi-use. */
-    readonly ip: string | null;
-    /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
-    labels: string[];
-    /** Unix timestamp (seconds) when token was created */
-    readonly created: number;
-    /** Unix timestamp (seconds) when token expires, null for never */
-    readonly expires: number | null;
-    /** Consumption timestamp. Single-use: gates re-use (set once). Multi-use: refreshed on every claim. Null = never claimed. */
-    readonly used: number | null;
-}
 /**
  * Token as returned by the list endpoint.
- * Shows 7-char management ID, omits account and hash.
+ * The secret is shown once at creation and never again — listings carry
+ * only the management identifier and lifecycle metadata.
  */
 export interface TokenListItem {
     /** 7-char management identifier (e.g., "a1b2c3d") */
@@ -212,7 +192,7 @@ export interface TokenListItem {
     readonly created: number;
     /** Unix timestamp (seconds) when token expires, null for never */
     readonly expires: number | null;
-    /** Consumption timestamp. Single-use: gates re-use (set once). Multi-use: refreshed on every claim. Null = never claimed. */
+    /** Unix timestamp (seconds) of the last request authenticated with this token, null if never used */
     readonly used: number | null;
 }
 /**
@@ -249,7 +229,7 @@ export declare const AccountPlan: {
     readonly TERMINATING: "terminating";
     readonly TERMINATED: "terminated";
 };
-export type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
+export type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
  * Account usage metrics — always available regardless of billing provider.
  */
@@ -281,6 +261,20 @@ export interface Account {
     /** Grace period expiration (unix seconds), null if no grace period active */
     readonly grace: number | null;
 }
+/**
+ * Account as returned by `GET /account` — the entity plus how the request
+ * was authorized, so `whoami` can answer "what credential am I holding?".
+ * Request-scoped fields live on the response type, never on the entity
+ * (the `DeploymentCreateResponse` pattern).
+ */
+export interface AccountGetResponse extends Account {
+    /** How the request that produced this response was authorized. */
+    readonly authMethod: AuthMethodType;
+    /** Present (and true) only when the caller is an operator acting as themselves. */
+    readonly isAdmin?: true;
+    /** Present only during read-only admin impersonation: the operator's account id. */
+    readonly impersonatedBy?: string;
+}
 /**
  * Account-specific configuration overrides
  * Allows per-account customization of limits without changing plan
@@ -330,7 +324,7 @@ export declare const ErrorType: {
     /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
     readonly Config: "config_error";
 };
-export type ErrorType = typeof ErrorType[keyof typeof ErrorType];
+export type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];
 /**
  * Standard error response format used everywhere
  */
@@ -438,15 +432,14 @@ export declare class ShipError extends Error {
  */
 export declare function isShipError(error: unknown): error is ShipError;
 /**
- * Plan-based platform limits returned by the `/config` endpoint.
+ * Plan-based platform limits returned by the `/limits` endpoint.
  *
  * The SDK fetches these once on first API call to drive client-side
  * file-size / file-count / total-size validation that mirrors what the API
  * would enforce server-side. Limits vary by account plan.
  *
- * Distinct from `ResolvedConfig` (which carries the *client's* credentials
- * and API URL after defaulting); this one carries the *platform's* posted
- * caps for the current account.
+ * These are the *platform's* posted caps for the current account — server
+ * truth delivered at runtime, never hard-coded on the client.
  */
 export interface PlatformLimits {
     /** Maximum size in bytes for a single file. */
@@ -525,6 +518,25 @@ export interface PingResponse {
     /** Optional timestamp */
     timestamp?: number;
 }
+/**
+ * How a request (or recorded activity) was authorized.
+ *
+ * Client populations: `SESSION` (first-party cookie), `API_KEY` (`ship-`
+ * key), `TOKEN` (`deploy-` deploy token), `AGENT` (anonymous public deploy —
+ * no credential; the platform grants the public-account identity per
+ * request), `OAUTH` (delegated access token). Server populations: `WEBHOOK`
+ * (signed webhook processing), `SYSTEM` (scheduled/background jobs).
+ */
+export declare const AuthMethod: {
+    readonly SESSION: "session";
+    readonly API_KEY: "apiKey";
+    readonly TOKEN: "token";
+    readonly AGENT: "agent";
+    readonly OAUTH: "oauth";
+    readonly WEBHOOK: "webhook";
+    readonly SYSTEM: "system";
+};
+export type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
 /**
  * Shape constants for API keys (`ship-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
@@ -540,26 +552,57 @@ export declare const API_KEY: {
     readonly HINT_LENGTH: 4;
 };
 /**
- * Shape constants for deploy tokens (`token-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export declare const DEPLOY_TOKEN: {
     /** Prefix that identifies a deploy token. */
-    readonly PREFIX: "token-";
+    readonly PREFIX: "deploy-";
     /** Number of hex characters following the prefix. */
     readonly HEX_LENGTH: 64;
-    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 70`). */
-    readonly TOTAL_LENGTH: 70;
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 71`). */
+    readonly TOTAL_LENGTH: 71;
 };
-export declare const AuthMethod: {
-    readonly SESSION: "session";
+/**
+ * Shape constants for caller identifiers (the `X-Caller` instance-identity
+ * header — rate-limit bucketing for multi-tenant orchestrators). The API
+ * normalizes case and silently ignores malformed values (the header is
+ * unauthenticated); clients validate at the boundary via `validateCaller`,
+ * so a value the server would drop fails fast instead.
+ */
+export declare const CALLER: {
+    /** HTTP header name. */
+    readonly HEADER: "X-Caller";
+    /** Maximum identifier length. */
+    readonly MAX_LENGTH: 128;
+    /** Allowed characters: alphanumeric, dot, underscore, hyphen. */
+    readonly PATTERN: RegExp;
+};
+/**
+ * Token populations distinguishable by shape. The platform carries every
+ * client token in one wire slot (`Authorization: Bearer <value>`) and
+ * classifies by value, never by a side channel — this is the classifier.
+ *
+ * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
+ * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
+ * straight into an auth method and the pair can never drift. `OPAQUE` is any
+ * other value — shape says nothing about it, so only a lookup can. Today the
+ * server refuses every opaque bearer; the OAuth access-token population
+ * resolves there when the authorization server ships.
+ */
+export declare const TokenKind: {
     readonly API_KEY: "apiKey";
-    readonly TOKEN: "token";
-    readonly OAUTH: "oauth";
-    readonly WEBHOOK: "webhook";
-    readonly SYSTEM: "system";
+    readonly DEPLOY_TOKEN: "token";
+    readonly OPAQUE: "opaque";
 };
-export type AuthMethodType = typeof AuthMethod[keyof typeof AuthMethod];
+export type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
+/**
+ * Classify a client token by shape. The single dispatch used by both sides
+ * of the wire: API auth middleware (which population is this credential?)
+ * and SDK validation (which format rules apply before sending?). Sharing it
+ * is what guarantees client and server can never disagree on dispatch.
+ */
+export declare function classifyToken(token: string): TokenKindType;
 /**
  * OAuth scope vocabulary for delegated third-party access tokens.
  * Single source of truth used by the authorization server (advertised in
@@ -578,7 +621,7 @@ export declare const OAuthScope: {
     readonly DOMAINS_READ: "domains:read";
     readonly DOMAINS_WRITE: "domains:write";
 };
-export type OAuthScopeType = typeof OAuthScope[keyof typeof OAuthScope];
+export type OAuthScopeType = (typeof OAuthScope)[keyof typeof OAuthScope];
 export declare const DEPLOYMENT_CONFIG_FILENAME = "ship.json";
 /** Default ship.json config for SPA routing. Single source of truth — used by both API and SDK. */
 export declare const SPA_DEFAULT_CONFIG: {
@@ -595,6 +638,19 @@ export declare function validateApiKey(apiKey: string): void;
  * Validate deploy token format
  */
 export declare function validateDeployToken(deployToken: string): void;
+/**
+ * Validate a client token of any population. Classifies by shape and applies
+ * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
+ * validated strictly; opaque tokens (OAuth access tokens, future populations)
+ * only need to be non-empty — their validity is the server's to decide.
+ */
+export declare function validateToken(token: string): void;
+/**
+ * Validate a caller identifier against the `CALLER` shape. The server
+ * silently ignores malformed values (the header is unauthenticated); clients
+ * call this at configuration time so the drop never silently happens.
+ */
+export declare function validateCaller(caller: string): void;
 /**
  * Validate API URL format
  */
@@ -656,24 +712,6 @@ export interface StaticFile {
     /** The size of the file in bytes. */
     size: number;
 }
-/**
- * Resolved client configuration with `apiUrl` defaulted.
- *
- * Produced by the SDK after layering its credential sources (constructor
- * options on top of `SHIP_*` env vars in Node; constructor options only in
- * Browser) and applying the `DEFAULT_API` fallback. File-based sources
- * (`.shiprc`, `package.json` `"ship"` key) are the CLI's responsibility and
- * are merged in *before* construction — by the time a `ResolvedConfig`
- * exists, every source has already collapsed into the constructor argument.
- */
-export interface ResolvedConfig {
-    /** API URL — always present after resolution, defaults to `DEFAULT_API`. */
-    apiUrl: string;
-    /** API key for authenticated deployments. */
-    apiKey?: string;
-    /** Deploy token used as the request credential (`token-{64-hex}`). */
-    deployToken?: string;
-}
 /**
  * Progress information for deploy/upload operations.
  * Provides consistent percentage-based progress with byte-level details.
@@ -727,6 +765,8 @@ export interface DeploymentUploadOptions {
     prerender?: boolean;
     /** @internal Trigger server-side SPA detection. Only available via /upload endpoint. */
     spa?: boolean;
+    /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
+    captcha?: string;
 }
 /**
  * Deployment resource interface - the contract all implementations must follow
@@ -766,7 +806,7 @@ export interface DomainResource {
  * Account resource interface - the contract all implementations must follow
  */
 export interface AccountResource {
-    get: () => Promise<Account>;
+    get: () => Promise<AccountGetResponse>;
 }
 /**
  * Token resource interface - the contract all implementations must follow
@@ -884,7 +924,7 @@ export declare const FileValidationStatus: {
     /** File passed validation and is ready for deployment */
     readonly READY: "ready";
 };
-export type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
+export type FileValidationStatusType = (typeof FileValidationStatus)[keyof typeof FileValidationStatus];
 /**
  * A validation issue with a display-ready message
  *

package/dist/index.js

@@ -12,7 +12,7 @@ export const DeploymentStatus = {
     PENDING: 'pending',
     SUCCESS: 'success',
     FAILED: 'failed',
-    DELETING: 'deleting'
+    DELETING: 'deleting',
 };
 // =============================================================================
 // DOMAIN TYPES
@@ -29,7 +29,7 @@ export const DomainStatus = {
     PENDING: 'pending',
     PARTIAL: 'partial',
     SUCCESS: 'success',
-    PAUSED: 'paused'
+    PAUSED: 'paused',
 };
 // =============================================================================
 // ACCOUNT TYPES
@@ -44,7 +44,7 @@ export const AccountPlan = {
     ENTERPRISE: 'enterprise',
     SUSPENDED: 'suspended',
     TERMINATING: 'terminating',
-    TERMINATED: 'terminated'
+    TERMINATED: 'terminated',
 };
 // =============================================================================
 // ERROR SYSTEM
@@ -100,7 +100,13 @@ const CLIENT_ONLY_ERROR_TYPES = new Set([
  * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
-    client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Forbidden, ErrorType.Validation]),
+    client: new Set([
+        ErrorType.Business,
+        ErrorType.Config,
+        ErrorType.File,
+        ErrorType.Forbidden,
+        ErrorType.Validation,
+    ]),
     network: new Set([ErrorType.Network]),
     auth: new Set([ErrorType.Authentication]),
 };
@@ -111,7 +117,7 @@ const ERROR_CATEGORIES = {
  * `CLIENT_ONLY_ERROR_TYPES` so adding a new server-producible type to
  * `ErrorType` is automatically picked up.
  */
-const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter(t => !CLIENT_ONLY_ERROR_TYPES.has(t)));
+const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter((t) => !CLIENT_ONLY_ERROR_TYPES.has(t)));
 /**
  * Simple unified error class for both API and SDK
  */
@@ -132,14 +138,12 @@ export class ShipError extends Error {
         // tag (see `ShipError.authentication` JSDoc) — these are server-side
         // diagnostics like 'session_invalid' that must not leak to clients.
         const authDetails = this.details;
-        const details = this.type === ErrorType.Authentication && authDetails?.internal
-            ? undefined
-            : this.details;
+        const details = this.type === ErrorType.Authentication && authDetails?.internal ? undefined : this.details;
         return {
             error: this.type,
             message: this.message,
             status: this.status,
-            details
+            details,
         };
     }
     /**
@@ -194,10 +198,14 @@ export class ShipError extends Error {
             // Body unreadable; fall through to operationName-derived message.
         }
         message = message || `${operationName || 'Request'} failed with status ${response.status}`;
-        const type = bodyType ?? (response.status === 401 ? ErrorType.Authentication :
-            response.status === 403 ? ErrorType.Forbidden :
-                response.status === 429 ? ErrorType.RateLimit :
-                    ErrorType.Api);
+        const type = bodyType ??
+            (response.status === 401
+                ? ErrorType.Authentication
+                : response.status === 403
+                    ? ErrorType.Forbidden
+                    : response.status === 429
+                        ? ErrorType.RateLimit
+                        : ErrorType.Api);
         return new ShipError(type, message, response.status, details);
     }
     /**
@@ -247,7 +255,7 @@ export class ShipError extends Error {
     static forbidden(message, details) {
         return new ShipError(ErrorType.Forbidden, message, 403, details);
     }
-    static rateLimit(message = "Too many requests", details) {
+    static rateLimit(message = 'Too many requests', details) {
         return new ShipError(ErrorType.RateLimit, message, 429, details);
     }
     /**
@@ -263,7 +271,7 @@ export class ShipError extends Error {
      * Use this pattern in API auth code; do not put client-visible info under
      * `internal`. Other `details` keys round-trip normally.
      */
-    static authentication(message = "Authentication required", details) {
+    static authentication(message = 'Authentication required', details) {
         return new ShipError(ErrorType.Authentication, message, 401, details);
     }
     static business(message, status = 400, details) {
@@ -332,21 +340,47 @@ export function isShipError(error) {
  */
 export const BLOCKED_EXTENSIONS = new Set([
     // Executables
-    'exe', 'msi', 'dll', 'scr', 'bat', 'cmd', 'com', 'pif', 'app', 'deb', 'rpm',
+    'exe',
+    'msi',
+    'dll',
+    'scr',
+    'bat',
+    'cmd',
+    'com',
+    'pif',
+    'app',
+    'deb',
+    'rpm',
     // Installers
-    'pkg', 'mpkg',
+    'pkg',
+    'mpkg',
     // Disk images
-    'dmg', 'iso', 'img',
+    'dmg',
+    'iso',
+    'img',
     // Malware vectors
-    'cab', 'cpl', 'chm',
+    'cab',
+    'cpl',
+    'chm',
     // Dangerous scripts
-    'ps1', 'vbs', 'vbe', 'ws', 'wsf', 'wsc', 'wsh', 'reg',
+    'ps1',
+    'vbs',
+    'vbe',
+    'ws',
+    'wsf',
+    'wsc',
+    'wsh',
+    'reg',
     // Java
-    'jar', 'jnlp',
+    'jar',
+    'jnlp',
     // Mobile/browser packages
-    'apk', 'crx',
+    'apk',
+    'crx',
     // Shortcut/link
-    'lnk', 'inf', 'hta',
+    'lnk',
+    'inf',
+    'hta',
 ]);
 /**
  * Check if a filename has a blocked extension.
@@ -381,6 +415,7 @@ export function isBlockedExtension(filename) {
  *
  * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
  */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: blocking control characters is this regex's purpose
 export const UNSAFE_FILENAME_CHARS = /[\x00-\x1f\x7f#?%\\<>"]/;
 /**
  * Check if a filename contains unsafe characters.
@@ -415,8 +450,33 @@ export const UNBUILT_PROJECT_MARKERS = new Set([
  */
 export function hasUnbuiltMarker(filePath) {
     const segments = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
-    return segments.some(s => UNBUILT_PROJECT_MARKERS.has(s));
+    return segments.some((s) => UNBUILT_PROJECT_MARKERS.has(s));
 }
+// =============================================================================
+// CREDENTIAL SHAPES
+// =============================================================================
+// The one address for credential vocabulary: how a request is authorized
+// (AuthMethod), the shapes that distinguish populations on the wire
+// (API_KEY, DEPLOY_TOKEN, CALLER), the single dispatch over them (TokenKind,
+// classifyToken), and the delegated-access scopes (OAuthScope).
+/**
+ * How a request (or recorded activity) was authorized.
+ *
+ * Client populations: `SESSION` (first-party cookie), `API_KEY` (`ship-`
+ * key), `TOKEN` (`deploy-` deploy token), `AGENT` (anonymous public deploy —
+ * no credential; the platform grants the public-account identity per
+ * request), `OAUTH` (delegated access token). Server populations: `WEBHOOK`
+ * (signed webhook processing), `SYSTEM` (scheduled/background jobs).
+ */
+export const AuthMethod = {
+    SESSION: 'session',
+    API_KEY: 'apiKey',
+    TOKEN: 'token',
+    AGENT: 'agent',
+    OAUTH: 'oauth',
+    WEBHOOK: 'webhook',
+    SYSTEM: 'system',
+};
 /**
  * Shape constants for API keys (`ship-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
@@ -432,26 +492,62 @@ export const API_KEY = {
     HINT_LENGTH: 4,
 };
 /**
- * Shape constants for deploy tokens (`token-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export const DEPLOY_TOKEN = {
     /** Prefix that identifies a deploy token. */
-    PREFIX: 'token-',
+    PREFIX: 'deploy-',
     /** Number of hex characters following the prefix. */
     HEX_LENGTH: 64,
-    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 70`). */
-    TOTAL_LENGTH: 70,
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 71`). */
+    TOTAL_LENGTH: 71,
 };
-// Authentication Method Constants
-export const AuthMethod = {
-    SESSION: 'session',
-    API_KEY: 'apiKey',
-    TOKEN: 'token',
-    OAUTH: 'oauth',
-    WEBHOOK: 'webhook',
-    SYSTEM: 'system'
+/**
+ * Shape constants for caller identifiers (the `X-Caller` instance-identity
+ * header — rate-limit bucketing for multi-tenant orchestrators). The API
+ * normalizes case and silently ignores malformed values (the header is
+ * unauthenticated); clients validate at the boundary via `validateCaller`,
+ * so a value the server would drop fails fast instead.
+ */
+export const CALLER = {
+    /** HTTP header name. */
+    HEADER: 'X-Caller',
+    /** Maximum identifier length. */
+    MAX_LENGTH: 128,
+    /** Allowed characters: alphanumeric, dot, underscore, hyphen. */
+    PATTERN: /^[a-zA-Z0-9._-]+$/,
 };
+/**
+ * Token populations distinguishable by shape. The platform carries every
+ * client token in one wire slot (`Authorization: Bearer <value>`) and
+ * classifies by value, never by a side channel — this is the classifier.
+ *
+ * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
+ * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
+ * straight into an auth method and the pair can never drift. `OPAQUE` is any
+ * other value — shape says nothing about it, so only a lookup can. Today the
+ * server refuses every opaque bearer; the OAuth access-token population
+ * resolves there when the authorization server ships.
+ */
+export const TokenKind = {
+    API_KEY: AuthMethod.API_KEY,
+    DEPLOY_TOKEN: AuthMethod.TOKEN,
+    OPAQUE: 'opaque',
+};
+/**
+ * Classify a client token by shape. The single dispatch used by both sides
+ * of the wire: API auth middleware (which population is this credential?)
+ * and SDK validation (which format rules apply before sending?). Sharing it
+ * is what guarantees client and server can never disagree on dispatch.
+ */
+export function classifyToken(token) {
+    if (token.startsWith(API_KEY.PREFIX))
+        return TokenKind.API_KEY;
+    if (token.startsWith(DEPLOY_TOKEN.PREFIX))
+        return TokenKind.DEPLOY_TOKEN;
+    return TokenKind.OPAQUE;
+}
 /**
  * OAuth scope vocabulary for delegated third-party access tokens.
  * Single source of truth used by the authorization server (advertised in
@@ -470,41 +566,73 @@ export const OAuthScope = {
     DOMAINS_READ: 'domains:read',
     DOMAINS_WRITE: 'domains:write',
 };
-// Deployment Configuration
+// =============================================================================
+// DEPLOYMENT CONFIGURATION CONSTANTS
+// =============================================================================
 export const DEPLOYMENT_CONFIG_FILENAME = 'ship.json';
 /** Default ship.json config for SPA routing. Single source of truth — used by both API and SDK. */
-export const SPA_DEFAULT_CONFIG = { rewrites: [{ source: '/(.*)', destination: '/index.html' }] };
+export const SPA_DEFAULT_CONFIG = {
+    rewrites: [{ source: '/(.*)', destination: '/index.html' }],
+};
 // =============================================================================
 // VALIDATION UTILITIES
 // =============================================================================
 /**
- * Validate API key format
+ * Shared rule for prefixed credentials: `{PREFIX}{HEX_LENGTH hex chars}`.
+ * The regex derives from the shape constants, so the validators can never
+ * drift from the shapes `classifyToken` dispatches on.
  */
-export function validateApiKey(apiKey) {
-    if (!apiKey.startsWith(API_KEY.PREFIX)) {
-        throw ShipError.validation(`API key must start with "${API_KEY.PREFIX}"`);
+function validatePrefixedCredential(value, shape, label) {
+    if (!value.startsWith(shape.PREFIX)) {
+        throw ShipError.validation(`${label} must start with "${shape.PREFIX}"`);
     }
-    if (apiKey.length !== API_KEY.TOTAL_LENGTH) {
-        throw ShipError.validation(`API key must be ${API_KEY.TOTAL_LENGTH} characters total (${API_KEY.PREFIX} + ${API_KEY.HEX_LENGTH} hex chars)`);
+    if (value.length !== shape.TOTAL_LENGTH) {
+        throw ShipError.validation(`${label} must be ${shape.TOTAL_LENGTH} characters total (${shape.PREFIX} + ${shape.HEX_LENGTH} hex chars)`);
     }
-    const hexPart = apiKey.slice(API_KEY.PREFIX.length);
-    if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-        throw ShipError.validation(`API key must contain ${API_KEY.HEX_LENGTH} hexadecimal characters after "${API_KEY.PREFIX}" prefix`);
+    const hexPart = value.slice(shape.PREFIX.length);
+    if (!new RegExp(`^[a-f0-9]{${shape.HEX_LENGTH}}$`, 'i').test(hexPart)) {
+        throw ShipError.validation(`${label} must contain ${shape.HEX_LENGTH} hexadecimal characters after "${shape.PREFIX}" prefix`);
     }
 }
+/**
+ * Validate API key format
+ */
+export function validateApiKey(apiKey) {
+    validatePrefixedCredential(apiKey, API_KEY, 'API key');
+}
 /**
  * Validate deploy token format
  */
 export function validateDeployToken(deployToken) {
-    if (!deployToken.startsWith(DEPLOY_TOKEN.PREFIX)) {
-        throw ShipError.validation(`Deploy token must start with "${DEPLOY_TOKEN.PREFIX}"`);
-    }
-    if (deployToken.length !== DEPLOY_TOKEN.TOTAL_LENGTH) {
-        throw ShipError.validation(`Deploy token must be ${DEPLOY_TOKEN.TOTAL_LENGTH} characters total (${DEPLOY_TOKEN.PREFIX} + ${DEPLOY_TOKEN.HEX_LENGTH} hex chars)`);
+    validatePrefixedCredential(deployToken, DEPLOY_TOKEN, 'Deploy token');
+}
+/**
+ * Validate a client token of any population. Classifies by shape and applies
+ * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
+ * validated strictly; opaque tokens (OAuth access tokens, future populations)
+ * only need to be non-empty — their validity is the server's to decide.
+ */
+export function validateToken(token) {
+    switch (classifyToken(token)) {
+        case TokenKind.API_KEY:
+            validateApiKey(token);
+            return;
+        case TokenKind.DEPLOY_TOKEN:
+            validateDeployToken(token);
+            return;
+        case TokenKind.OPAQUE:
+            if (!token)
+                throw ShipError.validation('Token must be a non-empty string');
     }
-    const hexPart = deployToken.slice(DEPLOY_TOKEN.PREFIX.length);
-    if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-        throw ShipError.validation(`Deploy token must contain ${DEPLOY_TOKEN.HEX_LENGTH} hexadecimal characters after "${DEPLOY_TOKEN.PREFIX}" prefix`);
+}
+/**
+ * Validate a caller identifier against the `CALLER` shape. The server
+ * silently ignores malformed values (the header is unauthenticated); clients
+ * call this at configuration time so the drop never silently happens.
+ */
+export function validateCaller(caller) {
+    if (!caller || caller.length > CALLER.MAX_LENGTH || !CALLER.PATTERN.test(caller)) {
+        throw ShipError.validation(`Caller must be 1-${CALLER.MAX_LENGTH} characters: letters, digits, dots, underscores, or hyphens`);
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.1.0",
+  "version": "2.2.1-beta.0",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,14 +33,17 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.5.5",
     "@types/node": "^24.10.9",
-    "husky": "^9.1.7",
     "typescript": "^5.9.3",
     "vitest": "^2.1.8"
   },
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
-    "test": "vitest"
+    "test": "vitest",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/index.ts

@@ -14,10 +14,10 @@ export const DeploymentStatus = {
   PENDING: 'pending',
   SUCCESS: 'success',
   FAILED: 'failed',
-  DELETING: 'deleting'
+  DELETING: 'deleting',
 } as const;
 
-export type DeploymentStatusType = typeof DeploymentStatus[keyof typeof DeploymentStatus];
+export type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
 
 /**
  * Core deployment object - used in both API responses and SDK
@@ -49,7 +49,6 @@ export interface Deployment {
   readonly screenshot: string;
 }
 
-
 /**
  * Response from deployment creation. Extends Deployment with one-time fields
  * only present on creation (not on subsequent GET requests).
@@ -87,10 +86,10 @@ export const DomainStatus = {
   PENDING: 'pending',
   PARTIAL: 'partial',
   SUCCESS: 'success',
-  PAUSED: 'paused'
+  PAUSED: 'paused',
 } as const;
 
-export type DomainStatusType = typeof DomainStatus[keyof typeof DomainStatus];
+export type DomainStatusType = (typeof DomainStatus)[keyof typeof DomainStatus];
 
 /**
  * Core domain object - used in both API responses and SDK
@@ -206,31 +205,10 @@ export interface DomainValidateResponse {
 // TOKEN TYPES
 // =============================================================================
 
-/**
- * Deployment token for automated deployments
- */
-export interface Token {
-  /** 7-char management identifier */
-  readonly token: string;
-  /** The account this token belongs to */
-  readonly account: string;
-  /** SHA256 hash of the raw credential (auth lookups only, never exposed to users) */
-  readonly hash: string;
-  /** IP-lock. Non-null = single-use (claimable only from this IP, once); null = multi-use. */
-  readonly ip: string | null;
-  /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
-  labels: string[];
-  /** Unix timestamp (seconds) when token was created */
-  readonly created: number;
-  /** Unix timestamp (seconds) when token expires, null for never */
-  readonly expires: number | null;
-  /** Consumption timestamp. Single-use: gates re-use (set once). Multi-use: refreshed on every claim. Null = never claimed. */
-  readonly used: number | null;
-}
-
 /**
  * Token as returned by the list endpoint.
- * Shows 7-char management ID, omits account and hash.
+ * The secret is shown once at creation and never again — listings carry
+ * only the management identifier and lifecycle metadata.
  */
 export interface TokenListItem {
   /** 7-char management identifier (e.g., "a1b2c3d") */
@@ -241,7 +219,7 @@ export interface TokenListItem {
   readonly created: number;
   /** Unix timestamp (seconds) when token expires, null for never */
   readonly expires: number | null;
-  /** Consumption timestamp. Single-use: gates re-use (set once). Multi-use: refreshed on every claim. Null = never claimed. */
+  /** Unix timestamp (seconds) of the last request authenticated with this token, null if never used */
   readonly used: number | null;
 }
 
@@ -283,10 +261,10 @@ export const AccountPlan = {
   ENTERPRISE: 'enterprise',
   SUSPENDED: 'suspended',
   TERMINATING: 'terminating',
-  TERMINATED: 'terminated'
+  TERMINATED: 'terminated',
 } as const;
 
-export type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
+export type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 
 /**
  * Account usage metrics — always available regardless of billing provider.
@@ -321,6 +299,21 @@ export interface Account {
   readonly grace: number | null;
 }
 
+/**
+ * Account as returned by `GET /account` — the entity plus how the request
+ * was authorized, so `whoami` can answer "what credential am I holding?".
+ * Request-scoped fields live on the response type, never on the entity
+ * (the `DeploymentCreateResponse` pattern).
+ */
+export interface AccountGetResponse extends Account {
+  /** How the request that produced this response was authorized. */
+  readonly authMethod: AuthMethodType;
+  /** Present (and true) only when the caller is an operator acting as themselves. */
+  readonly isAdmin?: true;
+  /** Present only during read-only admin impersonation: the operator's account id. */
+  readonly impersonatedBy?: string;
+}
+
 /**
  * Account-specific configuration overrides
  * Allows per-account customization of limits without changing plan
@@ -376,7 +369,7 @@ export const ErrorType = {
   Config: 'config_error',
 } as const;
 
-export type ErrorType = typeof ErrorType[keyof typeof ErrorType];
+export type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];
 
 /**
  * Error types that originate exclusively on the client (HTTP clients, SDK
@@ -397,7 +390,13 @@ const CLIENT_ONLY_ERROR_TYPES = new Set<string>([
  * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
-  client: new Set<ErrorType>([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Forbidden, ErrorType.Validation]),
+  client: new Set<ErrorType>([
+    ErrorType.Business,
+    ErrorType.Config,
+    ErrorType.File,
+    ErrorType.Forbidden,
+    ErrorType.Validation,
+  ]),
   network: new Set<ErrorType>([ErrorType.Network]),
   auth: new Set<ErrorType>([ErrorType.Authentication]),
 } as const;
@@ -410,7 +409,7 @@ const ERROR_CATEGORIES = {
  * `ErrorType` is automatically picked up.
  */
 const SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
-  Object.values(ErrorType).filter(t => !CLIENT_ONLY_ERROR_TYPES.has(t)),
+  Object.values(ErrorType).filter((t) => !CLIENT_ONLY_ERROR_TYPES.has(t)),
 );
 
 /**
@@ -447,15 +446,14 @@ export class ShipError extends Error {
     // tag (see `ShipError.authentication` JSDoc) — these are server-side
     // diagnostics like 'session_invalid' that must not leak to clients.
     const authDetails = this.details as { internal?: unknown } | undefined;
-    const details = this.type === ErrorType.Authentication && authDetails?.internal
-      ? undefined
-      : this.details;
+    const details =
+      this.type === ErrorType.Authentication && authDetails?.internal ? undefined : this.details;
 
     return {
       error: this.type,
       message: this.message,
       status: this.status,
-      details
+      details,
     };
   }
 
@@ -481,10 +479,7 @@ export class ShipError extends Error {
    * Async because it reads the response body. Returns rather than throws so
    * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
    */
-  static async fromHttpResponse(
-    response: Response,
-    operationName?: string,
-  ): Promise<ShipError> {
+  static async fromHttpResponse(response: Response, operationName?: string): Promise<ShipError> {
     let message: string | undefined;
     let details: unknown;
     let bodyType: ErrorType | undefined;
@@ -512,12 +507,15 @@ export class ShipError extends Error {
 
     message = message || `${operationName || 'Request'} failed with status ${response.status}`;
 
-    const type = bodyType ?? (
-      response.status === 401 ? ErrorType.Authentication :
-      response.status === 403 ? ErrorType.Forbidden :
-      response.status === 429 ? ErrorType.RateLimit :
-      ErrorType.Api
-    );
+    const type =
+      bodyType ??
+      (response.status === 401
+        ? ErrorType.Authentication
+        : response.status === 403
+          ? ErrorType.Forbidden
+          : response.status === 429
+            ? ErrorType.RateLimit
+            : ErrorType.Api);
 
     return new ShipError(type, message, response.status, details);
   }
@@ -576,7 +574,7 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Forbidden, message, 403, details);
   }
 
-  static rateLimit(message: string = "Too many requests", details?: unknown): ShipError {
+  static rateLimit(message: string = 'Too many requests', details?: unknown): ShipError {
     return new ShipError(ErrorType.RateLimit, message, 429, details);
   }
 
@@ -593,7 +591,7 @@ export class ShipError extends Error {
    * Use this pattern in API auth code; do not put client-visible info under
    * `internal`. Other `details` keys round-trip normally.
    */
-  static authentication(message: string = "Authentication required", details?: unknown): ShipError {
+  static authentication(message: string = 'Authentication required', details?: unknown): ShipError {
     return new ShipError(ErrorType.Authentication, message, 401, details);
   }
 
@@ -666,15 +664,14 @@ export function isShipError(error: unknown): error is ShipError {
 // =============================================================================
 
 /**
- * Plan-based platform limits returned by the `/config` endpoint.
+ * Plan-based platform limits returned by the `/limits` endpoint.
  *
  * The SDK fetches these once on first API call to drive client-side
  * file-size / file-count / total-size validation that mirrors what the API
  * would enforce server-side. Limits vary by account plan.
  *
- * Distinct from `ResolvedConfig` (which carries the *client's* credentials
- * and API URL after defaulting); this one carries the *platform's* posted
- * caps for the current account.
+ * These are the *platform's* posted caps for the current account — server
+ * truth delivered at runtime, never hard-coded on the client.
  */
 export interface PlatformLimits {
   /** Maximum size in bytes for a single file. */
@@ -701,21 +698,47 @@ export interface PlatformLimits {
  */
 export const BLOCKED_EXTENSIONS: ReadonlySet<string> = new Set([
   // Executables
-  'exe', 'msi', 'dll', 'scr', 'bat', 'cmd', 'com', 'pif', 'app', 'deb', 'rpm',
+  'exe',
+  'msi',
+  'dll',
+  'scr',
+  'bat',
+  'cmd',
+  'com',
+  'pif',
+  'app',
+  'deb',
+  'rpm',
   // Installers
-  'pkg', 'mpkg',
+  'pkg',
+  'mpkg',
   // Disk images
-  'dmg', 'iso', 'img',
+  'dmg',
+  'iso',
+  'img',
   // Malware vectors
-  'cab', 'cpl', 'chm',
+  'cab',
+  'cpl',
+  'chm',
   // Dangerous scripts
-  'ps1', 'vbs', 'vbe', 'ws', 'wsf', 'wsc', 'wsh', 'reg',
+  'ps1',
+  'vbs',
+  'vbe',
+  'ws',
+  'wsf',
+  'wsc',
+  'wsh',
+  'reg',
   // Java
-  'jar', 'jnlp',
+  'jar',
+  'jnlp',
   // Mobile/browser packages
-  'apk', 'crx',
+  'apk',
+  'crx',
   // Shortcut/link
-  'lnk', 'inf', 'hta',
+  'lnk',
+  'inf',
+  'hta',
 ]);
 
 /**
@@ -752,6 +775,7 @@ export function isBlockedExtension(filename: string): boolean {
  *
  * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
  */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: blocking control characters is this regex's purpose
 export const UNSAFE_FILENAME_CHARS = /[\x00-\x1f\x7f#?%\\<>"]/;
 
 /**
@@ -790,7 +814,7 @@ export const UNBUILT_PROJECT_MARKERS: ReadonlySet<string> = new Set([
  */
 export function hasUnbuiltMarker(filePath: string): boolean {
   const segments = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
-  return segments.some(s => UNBUILT_PROJECT_MARKERS.has(s));
+  return segments.some((s) => UNBUILT_PROJECT_MARKERS.has(s));
 }
 
 // =============================================================================
@@ -807,6 +831,35 @@ export interface PingResponse {
   timestamp?: number;
 }
 
+// =============================================================================
+// CREDENTIAL SHAPES
+// =============================================================================
+// The one address for credential vocabulary: how a request is authorized
+// (AuthMethod), the shapes that distinguish populations on the wire
+// (API_KEY, DEPLOY_TOKEN, CALLER), the single dispatch over them (TokenKind,
+// classifyToken), and the delegated-access scopes (OAuthScope).
+
+/**
+ * How a request (or recorded activity) was authorized.
+ *
+ * Client populations: `SESSION` (first-party cookie), `API_KEY` (`ship-`
+ * key), `TOKEN` (`deploy-` deploy token), `AGENT` (anonymous public deploy —
+ * no credential; the platform grants the public-account identity per
+ * request), `OAUTH` (delegated access token). Server populations: `WEBHOOK`
+ * (signed webhook processing), `SYSTEM` (scheduled/background jobs).
+ */
+export const AuthMethod = {
+  SESSION: 'session',
+  API_KEY: 'apiKey',
+  TOKEN: 'token',
+  AGENT: 'agent',
+  OAUTH: 'oauth',
+  WEBHOOK: 'webhook',
+  SYSTEM: 'system',
+} as const;
+
+export type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
+
 /**
  * Shape constants for API keys (`ship-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
@@ -823,29 +876,65 @@ export const API_KEY = {
 } as const;
 
 /**
- * Shape constants for deploy tokens (`token-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export const DEPLOY_TOKEN = {
   /** Prefix that identifies a deploy token. */
-  PREFIX: 'token-',
+  PREFIX: 'deploy-',
   /** Number of hex characters following the prefix. */
   HEX_LENGTH: 64,
-  /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 70`). */
-  TOTAL_LENGTH: 70,
+  /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 71`). */
+  TOTAL_LENGTH: 71,
 } as const;
 
-// Authentication Method Constants
-export const AuthMethod = {
-  SESSION: 'session',
-  API_KEY: 'apiKey',
-  TOKEN: 'token',
-  OAUTH: 'oauth',
-  WEBHOOK: 'webhook',
-  SYSTEM: 'system'
+/**
+ * Shape constants for caller identifiers (the `X-Caller` instance-identity
+ * header — rate-limit bucketing for multi-tenant orchestrators). The API
+ * normalizes case and silently ignores malformed values (the header is
+ * unauthenticated); clients validate at the boundary via `validateCaller`,
+ * so a value the server would drop fails fast instead.
+ */
+export const CALLER = {
+  /** HTTP header name. */
+  HEADER: 'X-Caller',
+  /** Maximum identifier length. */
+  MAX_LENGTH: 128,
+  /** Allowed characters: alphanumeric, dot, underscore, hyphen. */
+  PATTERN: /^[a-zA-Z0-9._-]+$/,
 } as const;
 
-export type AuthMethodType = typeof AuthMethod[keyof typeof AuthMethod];
+/**
+ * Token populations distinguishable by shape. The platform carries every
+ * client token in one wire slot (`Authorization: Bearer <value>`) and
+ * classifies by value, never by a side channel — this is the classifier.
+ *
+ * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
+ * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
+ * straight into an auth method and the pair can never drift. `OPAQUE` is any
+ * other value — shape says nothing about it, so only a lookup can. Today the
+ * server refuses every opaque bearer; the OAuth access-token population
+ * resolves there when the authorization server ships.
+ */
+export const TokenKind = {
+  API_KEY: AuthMethod.API_KEY,
+  DEPLOY_TOKEN: AuthMethod.TOKEN,
+  OPAQUE: 'opaque',
+} as const;
+
+export type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
+
+/**
+ * Classify a client token by shape. The single dispatch used by both sides
+ * of the wire: API auth middleware (which population is this credential?)
+ * and SDK validation (which format rules apply before sending?). Sharing it
+ * is what guarantees client and server can never disagree on dispatch.
+ */
+export function classifyToken(token: string): TokenKindType {
+  if (token.startsWith(API_KEY.PREFIX)) return TokenKind.API_KEY;
+  if (token.startsWith(DEPLOY_TOKEN.PREFIX)) return TokenKind.DEPLOY_TOKEN;
+  return TokenKind.OPAQUE;
+}
 
 /**
  * OAuth scope vocabulary for delegated third-party access tokens.
@@ -866,51 +955,94 @@ export const OAuthScope = {
   DOMAINS_WRITE: 'domains:write',
 } as const;
 
-export type OAuthScopeType = typeof OAuthScope[keyof typeof OAuthScope];
+export type OAuthScopeType = (typeof OAuthScope)[keyof typeof OAuthScope];
+
+// =============================================================================
+// DEPLOYMENT CONFIGURATION CONSTANTS
+// =============================================================================
 
-// Deployment Configuration
 export const DEPLOYMENT_CONFIG_FILENAME = 'ship.json';
 
 /** Default ship.json config for SPA routing. Single source of truth — used by both API and SDK. */
-export const SPA_DEFAULT_CONFIG = { rewrites: [{ source: '/(.*)', destination: '/index.html' }] } as const;
+export const SPA_DEFAULT_CONFIG = {
+  rewrites: [{ source: '/(.*)', destination: '/index.html' }],
+} as const;
 
 // =============================================================================
 // VALIDATION UTILITIES
 // =============================================================================
 
 /**
- * Validate API key format
+ * Shared rule for prefixed credentials: `{PREFIX}{HEX_LENGTH hex chars}`.
+ * The regex derives from the shape constants, so the validators can never
+ * drift from the shapes `classifyToken` dispatches on.
  */
-export function validateApiKey(apiKey: string): void {
-  if (!apiKey.startsWith(API_KEY.PREFIX)) {
-    throw ShipError.validation(`API key must start with "${API_KEY.PREFIX}"`);
+function validatePrefixedCredential(
+  value: string,
+  shape: { PREFIX: string; HEX_LENGTH: number; TOTAL_LENGTH: number },
+  label: string,
+): void {
+  if (!value.startsWith(shape.PREFIX)) {
+    throw ShipError.validation(`${label} must start with "${shape.PREFIX}"`);
   }
 
-  if (apiKey.length !== API_KEY.TOTAL_LENGTH) {
-    throw ShipError.validation(`API key must be ${API_KEY.TOTAL_LENGTH} characters total (${API_KEY.PREFIX} + ${API_KEY.HEX_LENGTH} hex chars)`);
+  if (value.length !== shape.TOTAL_LENGTH) {
+    throw ShipError.validation(
+      `${label} must be ${shape.TOTAL_LENGTH} characters total (${shape.PREFIX} + ${shape.HEX_LENGTH} hex chars)`,
+    );
   }
 
-  const hexPart = apiKey.slice(API_KEY.PREFIX.length);
-  if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-    throw ShipError.validation(`API key must contain ${API_KEY.HEX_LENGTH} hexadecimal characters after "${API_KEY.PREFIX}" prefix`);
+  const hexPart = value.slice(shape.PREFIX.length);
+  if (!new RegExp(`^[a-f0-9]{${shape.HEX_LENGTH}}$`, 'i').test(hexPart)) {
+    throw ShipError.validation(
+      `${label} must contain ${shape.HEX_LENGTH} hexadecimal characters after "${shape.PREFIX}" prefix`,
+    );
   }
 }
 
+/**
+ * Validate API key format
+ */
+export function validateApiKey(apiKey: string): void {
+  validatePrefixedCredential(apiKey, API_KEY, 'API key');
+}
+
 /**
  * Validate deploy token format
  */
 export function validateDeployToken(deployToken: string): void {
-  if (!deployToken.startsWith(DEPLOY_TOKEN.PREFIX)) {
-    throw ShipError.validation(`Deploy token must start with "${DEPLOY_TOKEN.PREFIX}"`);
-  }
+  validatePrefixedCredential(deployToken, DEPLOY_TOKEN, 'Deploy token');
+}
 
-  if (deployToken.length !== DEPLOY_TOKEN.TOTAL_LENGTH) {
-    throw ShipError.validation(`Deploy token must be ${DEPLOY_TOKEN.TOTAL_LENGTH} characters total (${DEPLOY_TOKEN.PREFIX} + ${DEPLOY_TOKEN.HEX_LENGTH} hex chars)`);
+/**
+ * Validate a client token of any population. Classifies by shape and applies
+ * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
+ * validated strictly; opaque tokens (OAuth access tokens, future populations)
+ * only need to be non-empty — their validity is the server's to decide.
+ */
+export function validateToken(token: string): void {
+  switch (classifyToken(token)) {
+    case TokenKind.API_KEY:
+      validateApiKey(token);
+      return;
+    case TokenKind.DEPLOY_TOKEN:
+      validateDeployToken(token);
+      return;
+    case TokenKind.OPAQUE:
+      if (!token) throw ShipError.validation('Token must be a non-empty string');
   }
+}
 
-  const hexPart = deployToken.slice(DEPLOY_TOKEN.PREFIX.length);
-  if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-    throw ShipError.validation(`Deploy token must contain ${DEPLOY_TOKEN.HEX_LENGTH} hexadecimal characters after "${DEPLOY_TOKEN.PREFIX}" prefix`);
+/**
+ * Validate a caller identifier against the `CALLER` shape. The server
+ * silently ignores malformed values (the header is unauthenticated); clients
+ * call this at configuration time so the drop never silently happens.
+ */
+export function validateCaller(caller: string): void {
+  if (!caller || caller.length > CALLER.MAX_LENGTH || !CALLER.PATTERN.test(caller)) {
+    throw ShipError.validation(
+      `Caller must be 1-${CALLER.MAX_LENGTH} characters: letters, digits, dots, underscores, or hyphens`,
+    );
   }
 }
 
@@ -1011,29 +1143,6 @@ export interface StaticFile {
   size: number;
 }
 
-// =============================================================================
-// PLATFORM CONFIGURATION
-// =============================================================================
-
-/**
- * Resolved client configuration with `apiUrl` defaulted.
- *
- * Produced by the SDK after layering its credential sources (constructor
- * options on top of `SHIP_*` env vars in Node; constructor options only in
- * Browser) and applying the `DEFAULT_API` fallback. File-based sources
- * (`.shiprc`, `package.json` `"ship"` key) are the CLI's responsibility and
- * are merged in *before* construction — by the time a `ResolvedConfig`
- * exists, every source has already collapsed into the constructor argument.
- */
-export interface ResolvedConfig {
-  /** API URL — always present after resolution, defaults to `DEFAULT_API`. */
-  apiUrl: string;
-  /** API key for authenticated deployments. */
-  apiKey?: string;
-  /** Deploy token used as the request credential (`token-{64-hex}`). */
-  deployToken?: string;
-}
-
 // =============================================================================
 // PROGRESS TRACKING
 // =============================================================================
@@ -1102,13 +1211,18 @@ export interface DeploymentUploadOptions {
   prerender?: boolean;
   /** @internal Trigger server-side SPA detection. Only available via /upload endpoint. */
   spa?: boolean;
+  /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
+  captcha?: string;
 }
 
 /**
  * Deployment resource interface - the contract all implementations must follow
  */
 export interface DeploymentResource {
-  upload: (input: DeployInput, options?: DeploymentUploadOptions) => Promise<DeploymentCreateResponse>;
+  upload: (
+    input: DeployInput,
+    options?: DeploymentUploadOptions,
+  ) => Promise<DeploymentCreateResponse>;
   list: () => Promise<DeploymentListResponse>;
   get: (id: string) => Promise<Deployment>;
   set: (id: string, options: { labels: string[] }) => Promise<Deployment>;
@@ -1119,7 +1233,10 @@ export interface DeploymentResource {
  * Domain resource interface - the contract all implementations must follow
  */
 export interface DomainResource {
-  set: (name: string, options?: { deployment?: string; labels?: string[] }) => Promise<DomainSetResult>;
+  set: (
+    name: string,
+    options?: { deployment?: string; labels?: string[] },
+  ) => Promise<DomainSetResult>;
   list: () => Promise<DomainListResponse>;
   get: (name: string) => Promise<Domain>;
   remove: (name: string) => Promise<void>;
@@ -1134,7 +1251,7 @@ export interface DomainResource {
  * Account resource interface - the contract all implementations must follow
  */
 export interface AccountResource {
-  get: () => Promise<Account>;
+  get: () => Promise<AccountGetResponse>;
 }
 
 /**
@@ -1169,7 +1286,6 @@ export interface BillingStatus {
   portal: string | null;
 }
 
-
 /**
  * Checkout session response from POST /billing/checkout
  */
@@ -1233,9 +1349,9 @@ export type ActivityEvent =
   | 'refund.created'
   | 'dispute.created'
   // Billing operational events (admin/debug only, not user-visible)
-  | 'billing.sync'    // Outbound: unit count pushed to payment provider
-  | 'billing.stale'   // Dropped: webhook predates last known state
-  | 'billing.race';   // Dropped: concurrent webhook already updated state
+  | 'billing.sync' // Outbound: unit count pushed to payment provider
+  | 'billing.stale' // Dropped: webhook predates last known state
+  | 'billing.race'; // Dropped: concurrent webhook already updated state
 
 /**
  * Activity events visible to users in the dashboard
@@ -1344,8 +1460,8 @@ export const FileValidationStatus = {
   READY: 'ready',
 } as const;
 
-export type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
-
+export type FileValidationStatusType =
+  (typeof FileValidationStatus)[keyof typeof FileValidationStatus];
 
 /**
  * A validation issue with a display-ready message
@@ -1588,4 +1704,4 @@ export function validatePassword(value: unknown): string | undefined {
     );
   }
   return trimmed;
-}
+}