@shipstatic/types 2.5.0 → 2.6.0

package/dist/index.d.ts

@@ -1009,30 +1009,35 @@ export declare const AuthMethod: {
 };
 export type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
 /**
- * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Shape constants for API keys (`ship-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export declare const API_KEY: {
     /** Prefix that identifies an API key. */
     readonly PREFIX: "ship-";
     /** Number of hex characters following the prefix. */
-    readonly HEX_LENGTH: 64;
-    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
-    readonly TOTAL_LENGTH: 69;
+    readonly HEX_LENGTH: 32;
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 37`). */
+    readonly TOTAL_LENGTH: 37;
     /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
     readonly HINT_LENGTH: 4;
 };
 /**
- * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
+ *
+ * Deliberately the same width as `API_KEY`: both are minted by one generator
+ * and classified by prefix alone, so a length that differed between them
+ * would be a second thing to know about a credential whose prefix already
+ * says what it is.
  */
 export declare const DEPLOY_TOKEN: {
     /** Prefix that identifies a deploy 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 = 71`). */
-    readonly TOTAL_LENGTH: 71;
+    readonly HEX_LENGTH: 32;
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
+    readonly TOTAL_LENGTH: 39;
 };
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity

package/dist/index.js

@@ -886,6 +886,28 @@ export function hasUnbuiltMarker(filePath) {
 // that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN, CALLER),
 // the single dispatch over them (TokenKind, classifyToken), and the
 // delegated-access scopes (OAuthScope).
+//
+// THE SHAPE LAW, in three clauses. Every secret the platform mints obeys it,
+// and `tests/validation-constants.test.ts` holds all three mechanically.
+//
+//  1. ONE ENTROPY STANDARD. Every minted random secret is `HEX_LENGTH` hex
+//     characters — one width for the whole platform, so "how long is a
+//     credential" has a single answer rather than one per population.
+//
+//  2. A PREFIX MARKS A SHARED SLOT, AND NOTHING ELSE. API keys and deploy
+//     tokens both arrive as `Authorization: Bearer`, so something must say
+//     which population a value belongs to: that is what the prefix IS, and
+//     `classifyToken` below is its only reader. Secrets that arrive somewhere
+//     unambiguous carry none — the deployment claim code reaches its own
+//     route in its own field, inside a URL whose path already says `/claim/`,
+//     so a prefix there would be a second name for what the route states.
+//
+//  3. NO PREFIX IS A PREFIX OF ANOTHER. This is what makes the dispatch
+//     order-independent, and it is the reason the populations are named on
+//     different axes (`ship-` for the product, `deploy-` for the capability)
+//     rather than sharing a stem. A `ship-` / `ship-deploy-` pair reads tidier
+//     and is a trap: every deploy token would also match the API-key branch,
+//     leaving correctness resting on the order of two `if`s.
 /**
  * Where human identity is mounted on the API host. The API mounts Better
  * Auth at this path (sign-in, sign-out, session reads, admin impersonation)
@@ -913,30 +935,35 @@ export const AuthMethod = {
     SYSTEM: 'system',
 };
 /**
- * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Shape constants for API keys (`ship-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export const API_KEY = {
     /** Prefix that identifies an API key. */
     PREFIX: 'ship-',
     /** Number of hex characters following the prefix. */
-    HEX_LENGTH: 64,
-    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
-    TOTAL_LENGTH: 69,
+    HEX_LENGTH: 32,
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 37`). */
+    TOTAL_LENGTH: 37,
     /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
     HINT_LENGTH: 4,
 };
 /**
- * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
+ *
+ * Deliberately the same width as `API_KEY`: both are minted by one generator
+ * and classified by prefix alone, so a length that differed between them
+ * would be a second thing to know about a credential whose prefix already
+ * says what it is.
  */
 export const DEPLOY_TOKEN = {
     /** Prefix that identifies a deploy 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 = 71`). */
-    TOTAL_LENGTH: 71,
+    HEX_LENGTH: 32,
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
+    TOTAL_LENGTH: 39,
 };
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepack": "pnpm run build",
     "clean": "rm -rf dist",
     "test": "vitest",
     "lint": "biome check .",
@@ -47,5 +48,9 @@
     "@types/node": "^24.13.3",
     "typescript": "^5.9.3",
     "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   }
 }

package/src/index.ts

@@ -1541,6 +1541,28 @@ export interface PingResponse {
 // that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN, CALLER),
 // the single dispatch over them (TokenKind, classifyToken), and the
 // delegated-access scopes (OAuthScope).
+//
+// THE SHAPE LAW, in three clauses. Every secret the platform mints obeys it,
+// and `tests/validation-constants.test.ts` holds all three mechanically.
+//
+//  1. ONE ENTROPY STANDARD. Every minted random secret is `HEX_LENGTH` hex
+//     characters — one width for the whole platform, so "how long is a
+//     credential" has a single answer rather than one per population.
+//
+//  2. A PREFIX MARKS A SHARED SLOT, AND NOTHING ELSE. API keys and deploy
+//     tokens both arrive as `Authorization: Bearer`, so something must say
+//     which population a value belongs to: that is what the prefix IS, and
+//     `classifyToken` below is its only reader. Secrets that arrive somewhere
+//     unambiguous carry none — the deployment claim code reaches its own
+//     route in its own field, inside a URL whose path already says `/claim/`,
+//     so a prefix there would be a second name for what the route states.
+//
+//  3. NO PREFIX IS A PREFIX OF ANOTHER. This is what makes the dispatch
+//     order-independent, and it is the reason the populations are named on
+//     different axes (`ship-` for the product, `deploy-` for the capability)
+//     rather than sharing a stem. A `ship-` / `ship-deploy-` pair reads tidier
+//     and is a trap: every deploy token would also match the API-key branch,
+//     leaving correctness resting on the order of two `if`s.
 
 /**
  * Where human identity is mounted on the API host. The API mounts Better
@@ -1573,31 +1595,36 @@ export const AuthMethod = {
 export type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
 
 /**
- * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Shape constants for API keys (`ship-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export const API_KEY = {
   /** Prefix that identifies an API key. */
   PREFIX: 'ship-',
   /** Number of hex characters following the prefix. */
-  HEX_LENGTH: 64,
-  /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
-  TOTAL_LENGTH: 69,
+  HEX_LENGTH: 32,
+  /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 37`). */
+  TOTAL_LENGTH: 37,
   /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
   HINT_LENGTH: 4,
 } as const;
 
 /**
- * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
+ *
+ * Deliberately the same width as `API_KEY`: both are minted by one generator
+ * and classified by prefix alone, so a length that differed between them
+ * would be a second thing to know about a credential whose prefix already
+ * says what it is.
  */
 export const DEPLOY_TOKEN = {
   /** Prefix that identifies a deploy 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 = 71`). */
-  TOTAL_LENGTH: 71,
+  HEX_LENGTH: 32,
+  /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
+  TOTAL_LENGTH: 39,
 } as const;
 
 /**